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Chapter 1. PowerShell Language and Environment 


Commands and Expressions 


PowerShell breaks any line that you enter into its individual units (tokens), and then interprets each token in one of two ways: as a command or 
as an expression. The difference is subtle: expressions support logic and flow control statements (such as if, foreach, and throw), 
whereas commands do not. 


You will often want to control the way that PowerShell interprets your statements, so Table 1-1 lists the available options. 


Statement 


Precedence control: () 


Expression subparse: 
$0 


Table 1-1. PowerShell evaluation controls 


Explanation 


Forces the evaluation ofa command or expression, similar to the way that parentheses are used to force the order of evaluation in a 
mathematical expression. 


For example: 


PS > 5 * (1 + 2) 
15 
PS > (dir) .Count 


Forces the evaluation of a command or expression, similar to the way that parentheses are used to force the order of evaluation in a 
mathematical expression. 


However, a subparse is as powerful as a subprogramand is required only when the subprogram contains logic or flow control 
statements. 


This statement is also used to expand dynamic information inside a string. 


For example: 


PS > "The answer is (2+2)" 
The answer is (2+2) 


PS > "The answer is $(2+2)" 
The answer is 4 


PS > Svalue = 10 

PS > $result = $( 
if ($value gt 0) { $true } 
else { $false }) 

PS > Sresult 

True 


Statement Explanation 
List evaluation: @ () Forces an expression to be evaluated as a list. If it is already a list, it will remain a list. If it is not, PowerShell temporarily treats it as one. 
For example: 


PS > "Hello".Length 
5 
PS > @("Hello") .Length 
1 
PS > ([PSCustomObject] @{ 
Propertyl = "Hello" 

Count = 100 }).Count 

100 

PS > @([PSCustomObject] @{ 
Propertyl = "Hello" 

Count = 100 }).Count 

1 


DATA evaluation: DATA Evaluates the given script block in the context of the PowerShell data language. The data language supports only data-centric features 
A ofthe PowerShell language. 


For example: 


PS > DATA { 1+1} 

2 

PS > DATA { $myVariable = "Test" } 
Assignment statements are not 
allowed in restricted language 
mode or a Data section. 


Comments 
To create single-line comments, begin a line with the # character. To create a block (or multiline) comment, surround the region with the 
characters <# and #>: 

# This is a regular comment 

<# This is a block comment 

function MyTest 

í "This should not be considered a function" 

} 

SmyVariable = 10; 


Block comment ends 
#> 


# This is regular script again 


Help Comments 


PowerShell creates help for your script or function by looking at its comments. Ifthe comments include any supported help tags, PowerShell 
adds those to the help for your command. 


Comment-based help supports the following tags, which are all case-insensitive: 
. SYNOPSIS 
A short summary of the command, ideally a single sentence. 


. DESCRIPTION 


A more detailed description of the command. 


. PARAMETER name 


A description of parameter name, with one for each parameter you want to describe. While you can write a . PARAMETER comment for 
each parameter, PowerShell also supports comments written directly above the parameter. Putting parameter help alongside the actual 
parameter makes it easier to read and maintain. 


. EXAMPLE 


An example of this command in use, with one for each example you want to provide. PowerShell treats the line immediately beneath the 
. EXAMPLE tag as the example command. If this line doesn’t contain any text that looks like a prompt, PowerShell adds a prompt before 
t. It treats lines that follow the initial line as additional output and example commentary. 


. INPUTS 
A short summary of pipeline input(s) supported by this command. For each input type, PowerShell’s built-in help follows this convention: 
System.String 


You can pipe a string that contains a path to 
Get-ChildItem. 


. OUTPUTS 
A short summary of items generated by this command. For each output type, PowerShell’s built-in help follows this convention: 
System. ServiceProcess.ServiceController 


This cmdlet returns objects that represent the 
services on the computer. 


. NOTES 
Any additional notes or remarks about this command. 


. LINK 
A link to a related help topic or command, with one . LINK tag per link. Ifthe related help topic is a URL, PowerShell launches that URL 
when the user supplies the -On line parameter to Get-Help for your command. 
While these are all of the supported help tags you are likely to use, comment-based help also supports tags for some of Get -He 1 p’s more 
obscure features: 


= .COMPONENT 


a .ROLE 


= .FUNCTIONALITY 


ae . FORWARDHELPTARGETNAME 


a . FORWARDHELPCATEGORY 


E .REMOTEHELPRUNS PACE 


a .EXTERNALHELP 


For more information about these tags, type Get-Help about_Comment_Based_Help. 


Variables 


PowerShell provides several ways to define and access variables, as summarized in Table 1-2. 


Table 1-2. PowerShell variable syntaxes 


Syntax Meaning 


. Syntax 


SsimpleVa 
riable = 
"Value" 


Svariable 
1 ti 
$variable 
a = 
"Valuel", 
"Value2" 


St 
arbitrary 
!@#@\ # {var 
}iable } 
= "Value" 


S{c:\file 
name. 
extension 


} 


[datatype 
J 

Svariable 
= "Value" 


[constrai 
iiel 

$variable 
= "Value" 


SSCOPE:va 
riable 


New-Item 
Variable: 
\variable 
-Value 
value 


Get-Item 
Variable: 
\variable 


Get- 
Variable 
variable 


New- 
Variable 
variable 
-Option 
option - 
Value 
value 


Meaning 


A simple variable name. The variable name must consist of alphanumeric characters. Variable names are not case-sensitive. 


Multiple variable assignment. PowerShell populates each variable fromthe value in the corresponding position on the righthand side. Extra values 
are assigned as a list to the last variable listed. 


An arbitrary variable name. The variable name must be surrounded by curly braces, but it may contain any characters. Curly braces in the variable 
name must be escaped with a backtick (`). 


Variable “Get and Set Content” syntax. This is similar to the arbitrary variable name syntax. If the name corresponds to a valid PowerShell path, you 
can get and set the content of the itemat that location by reading and writing to the variable. 


Strongly typed variable. Ensures that the variable may contain only data of the type you declare. PowerShell throws an error if it cannot coerce the 
data to this type when you assign it. 


Constrained variable. Ensures that the variable may contain only data that passes the supplied validation constraints: 


[ValidateLength(4, 10)] $a = "Hello" 


The supported validation constraints are the same as those supported as parameter validation attributes. 


Gets or sets the variable at that specific scope. Valid scope names are global (to make a variable available to the entire shell), script (to make a 
variable available only to the current script or persistent during module commands), local (to make a variable available only to the current scope 
and subscopes), and private (to make a variable available only to the current scope). The default scope is the current scope: global when 
defined interactively in the shell, script when defined outside any functions or script blocks in a script, and local elsewhere. 


Creates a new variable using the variable provider. 


Gets the variable using the variable provider or Get-Variable cmdlet. This lets you access extra information about the variable, such as its 
options and description. 


Creates a variable using the 
New-Variable cmdlet. This lets you provide extra information about the variable, such as its options and description. 
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NOTE 


Unlike some languages, PowerShell rounds (rather than truncates) numbers when it converts them to the [int] data type: 
PS > (3/2) 
1:5 


PS > [int] (3/2) 
2 


Booleans 


Boolean (true or false) variables are most commonly initialized to their literal values of $t rue and $ false. When PowerShell evaluates 
variables as part ofa Boolean expression (for example, an i £ statement), though, it maps them to a suitable Boolean representation, as listed in 
Table 1-3. 


Table 1-3. PowerShell Boolean interpretations 


Result Boolean representation 
Strue True 

Sfalse False 

Snull False 

Nonzero number True 

Zero False 

Nonempty string True 

Enpty string False 

Empty array False 

Single-element array The Boolean representation ofits single element 
Multi-element array True 


Hashtable (either empty or not) True 


Strings 
PowerShell offers several facilities for working with plain-text data. 


Literal and Expanding Strings 


To define a literal string (one in which no variable or escape expansion occurs), enclose it in single quotes: 


SmyString = 'hello `t SENV:SystemRoot' 


SmyString gets the actual value ofhello `t SENV:SystemRoot. 


To define an expanding string (one in which variable and escape expansion occur), enclose it in double quotes: 


SmyString = "hello `t SENV:SystemRoot" 


SmyString gets a value similar tohello C:\WINDOWS. 
To include a single quote in a single-quoted string or a double quote in a double-quoted string, include two of the quote characters in a row: 


PS > "Hello ""There™!" 
Hello "There"! 
PS > 'Hello ''There''!! 
Hello 'There!'! 
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NOTE 


To include a complex expression inside an expanding string, use a subexpression. For example: 
Sprompt = "$ (Get-Location) >" 


Sprompt gets a value similar to c: \temp >. 


Accessing the properties of an object requires a subexpression: 


Sversion = "Current PowerShell version is:" 
SPSVersionTable. PSVersion.Major 


Sversion gets a value similar to: 


Current PowerShell version is: 3 


Here Strings 


To define a here string (one that may span multiple lines), place the two characters @" at the beginning and the two characters " @ on their own 
Ine at the end. 


For example: 


SmyHereString = @" 

This text may span multiple lines, and may 
contain "quotes." 

"@ 


Here strings may be of either the literal (single-quoted) or expanding (double-quoted) variety. 


Escape Sequences 
PowerShell supports escape sequences inside strings, as listed in Table 1-4. 


Table 1-4. PowerShell escape sequences 


Sequence Meaning 

‘0 The null character. Often used as a record separator. 

`a The alarm character. Generates a beep when displayed on the console. 

`p The backspace character. The previous character remains in the string but is overwritten when displayed on the console. 
`e The escape character. Marks the beginning ofan ANSI escape sequence such as "`e [23“. 

pz A form feed. Creates a page break when printed on most printers. 

“n A newline. 

E A carriage return. Newlines in PowerShell are indicated entirely by the `n character, so this is rarely required. 

at A tab. 

~u{hex-code} A unicode character literal. Creates a character represented by the specified hexadecimal Unicode code point, such as “u{2265} ©). 
iy A vertical tab. 


'' (two single quotes) A single quote, when in a literal string. 
"" (two double quotes) A double quote, when in an expanding string. 


‘any other That character, taken literally. 
character 


Numbers 


PowerShell offers several options for interacting with numbers and numeric data. 


Simple Assignment 


To define a variable that holds numeric data, simply assign it as you would other variables. PowerShell automatically stores your data in a format 
that is sufficient to accurately hold it: 


SmyInt = 10 
SmyUnsignedint = 10u 
SmyUnsignedint = [uint] 10 
SmyInt gets the value of 10, as a (32-bit) integer. SmyUnsignedInt gets the value of 10 as an unsigned integer. 


SmyDouble = 3.14 


$myDouble gets the value of 3 . 14, as a (53-bit, 9 bits of precision) double. 


To explicitly assign a number as a byte (8-bit) or short (16-bit) number, use the y or s suffixes. Prefixing either with u creates an unsigned 
version of that data type. You can also use the [byte], [int16],and [short] casts: 


SmyByte = 127y 
SmyByte = [byte] 127 
SmyUnsignedByte = 127uy 


SmyShort = 32767s 
SmyShort = [int16] 32767 

SmyShort = [short] 32767 
SmyUnsignedShort = 32767us 
SmyUnsignedShort = [ushort] 32767 


To explicitly assign a number as a long (64-bit) integer or decimal (96-bit, 96 bits of precision), use the long (1) and decimal (a) suffixes. You 
can also use the [long] cast: 


SmyLong = 21474836481 
SmyLong = [long] 2147483648 


2147483648ul 
[ulong] 2147483648 


SmyUnsignedLong 
SmyUnsignedLong 


SmyDecimal = 0.999d 
To explicitly assign a number as a BigInteger (an arbitrary large integer with no upper or lower bounds), use the BigInteger (n) suffix: 
SmyBigInt = 99999999999999999999999999999n 


PowerShell also supports scientific notation, where e<number> represents multiplying the original number by the <n umbe r> power of 10: 


SmyPi = 3141592653e-9 


SmyPi gets the value of 3.141592653. 
The data types in PowerShell (integer, long integer, double, and decimal) are built on the .NET data types of the same names. 


Administrative Numeric Constants 


Since computer administrators rarely get the chance to work with numbers in even powers of 10, PowerShell offers the numeric constants of 
pb, tb, gb, mb, and kb to represent petabytes (1,125,899,906,842,624), terabytes (1,099,511,627,776), gigabytes (1,073,741,824), 
megabytes (1,048,576), and kilobytes (1,024), respectively: 


PS > S$downloadTime = (1gb + 250mb) / 120kb 
PS > SdownloadTime 
10871.4666666667 


You can combine these numeric multipliers with a data type as long as the result fits in that data type, such as 250ngb. 


Hexadecimal and Other Number Bases 
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To directly enter a hexadecimal number, use the hexadecimal prefix 0 x: 


SmyErrorCode = OxFE4A 


SmyErrorCode gets the integer value 65098. 
To directly enter a binary number, use the binary prefix Ob: 


SmyBinary = 0b101101010101 


SmyBinary gets the integer value of 2901. 


If you don’t know the hex or binary value as a constant or need to convert into Octal, use the [Convert] class fromthe .NET Framework. 
The first parameter is the value to convert, and the second parameter is the base (2, 8, 10, or 16): 


SmyOctal = [Convert] ::ToInt32("1234567", 8) 
SmyOctal gets the integer value of 342391. 

SmyHexString = [Convert] ::ToString (65098, 16) 
SmyHexString gets the string value of fe4a. 

SmyBinaryString = [Convert]::ToString(12345, 2) 


SmyBinaryString gets the string value of 11000000111001. 


NOTE 


See “Working with the .NET Framework” to learn more about using PowerShell to interact with the .NET Framework. 


Large Numbers 
To work with extremely large numbers, use the BigInt class. 


[BigInt] ::Pow (12345, 123) 
To do math with several large numbers, use the [BigInt] cast (or the n BigInt data type) for all operands: 


PS > 98123498123498123894n * 98123498123498123894n 
9628220883992139841085109029337773723236 


PS > Sval = "98123498123498123894" 
PS > ([BigInt] $val) * ([BigInt] $val) 
9628220883992139841085109029337773723236 


Imaginary and Complex Numbers 
To work with imaginary and complex numbers, use the System. Numerics.Complex class: 


PS > [System.Numerics.Complex]::ImaginaryOne * 
[System.Numerics.Complex]::ImaginaryOne | Format-—List 


Real 3 =i 
Imaginary : 0 


Magnitude : 1 
Phase : 3.14159265358979 


Arrays and Lists 


Array Definitions 
PowerShell arrays hold lists of data. The @ () (array cast) syntax tells PowerShell to treat the contents between the parentheses as an array. 
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To create an enpty array, type: 


SmyArray = @() 
To define a nonempty array, use a comma to separate its elements: 
SmySimpleArray = 1,"Two",3.14 
Arrays may optionally be only a single element long: 
SmyList = ,"Hello" 
Or, alternatively (using the array cast syntax): 
SmyList = @("Hello") 


Elements ofan array don’t need to be all of the same data type, unless you declare it as a strongly typed array. In the following example, the 
outer square brackets define a strongly typed variable (as mentioned in “Variables”, and int [] represents an array of integers: 


[int[]] SmyArray = 1,2,3.14 


In this mode, PowerShell generates an error if it cannot convert any of the elements in your list to the required data type. In this case, it rounds 
3.14 to the integer value of 3: 


PS > SmyArray [2] 
3 


NOTE 


To ensure that PowerShell treats collections of uncertain length (such as history lists or directory listings) as a list, use the list evaluation 
syntax @ (...) described in “Commands and Expressions”. 
Arrays can also be multidimensional jagged arrays (arrays within arrays): 


SmultiDimensional = @( 
(1,2,3,4), 
(5,6,7,8) 


$SmultiDimensional [0] [1] returns 2, coming from row 0, column 1. 


$SmultiDimensional [1] [3] returns 8, coming fromrow 1, column 3. 


To define a multidimensional array that is not jagged, create a multidimensional instance of the .NET type. For integers, that would be an array 
ofSystem. Int32: 


Smultidimensional = New-Object "Int32[,]" 2,4 
Smultidimensional[0,1] = 2 
Smultidimensional [1,3] = 8 


Array Access 


To access a specific element in an array, use the [ ] operator. PowerShell numbers your array elements starting at zero. Using $myArray = 
1,2,3,4,5, 6 as anexample: 


SmyArray [0] 
returns 1, the first element in the array. 
SmyArray [2] 


returns 3, the third element in the array. 


SmyArray [-1] 
retums 6, the last element of the array. 
SmyArray [-2] 


returns 5, the second-to-last element of the array. 


You can also access ranges of elements in your array: 


PS > SmyArray[0..2] 
1 
2 
3 


returns elements 0 through 2, inclusive. 


PS > SmyArray[-1..2] 
6 


1 

2 

3 
returns the final element, wraps around, and returns elements 0 through 2, inclusive. PowerShell wraps around because the first number in the 
range is negative, and the second number in the range is positive. 


PS > SmyArray[-1..-3] 
6 
5 
4 


returns the last element of the array through to the third-to-last element in the array, in descending order. PowerShell does not wrap around (and 
therefore scans backward in this case) because both numbers in the range share the same sign. 


Ifthe array being accessed might be null, you can use the null conditional array access operator (? [ ] ). The result of the expression will be null 
if the array being accessed did not exist. It will be the element at the specified index otherwise: 


(Get-Process -id 0) .Modules?[0] 


Array Slicing 
You can combine several of the statements in the previous section at once to extract more complex ranges from an array. Use the + sign to 
separate array ranges from explicit indexes: 
SmyArray[0,2,4] 
returns the elements at indices 0, 2, and 4. 
SmyArray[0,2+4..5] 
returns the elements at indices 0, 2, and 4 through 5, inclusive. 


SmyArray[,0+2..3+0,0] 


returns the elements at indices 0, 2 through 3 inclusive, 0, and 0 again. 


NOTE 


You can use the array slicing syntax to create arrays as well: 


SmyArray = ,0+2..3+0,0 
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Hashtables (Associative Arrays) 


Hashtable Definitions 
PowerShell Hashtables (also called associative arrays) let you associate keys with values. To define a hashtable, use the syntax: 


SmyHashtable = @{} 


You can initialize a hashtable with its key/value pairs when you create it. PowerShell assumes that the keys are strings, but the values may be 
any data type: 


SmyHashtable = @{ Keyl = "Valuel"; "Key 2" = 1,2,3; 3.14 = "Pi" } 


To define a hashtable that retains its insertion order, use the [ordered] cast: 


SorderedHash = [ordered] @{} 
SorderedHash ["NewKey"] = "Value" 


Hashtable Access 


To access or modify a specific element in an associative array, you can use either the array-access or property-access syntax: 
SmyHashtable["Key1"] 
returns "Valuel". 
SmyHashtable."Key 2" 
returns the array 1,2, 3. 
SmyHashtable["New Item"] = 5 
adds "New Item" to the hashtable. 
SmyHashtable."New Item" = 5 


also adds "New Item" to the hashtable. 


XML 
PowerShell supports XML as a native data type. To create an XML variable, cast a string to the [xm1] type: 


SmyXml = [xml] @" 
<AddressBook> 
<Person contactType="Personal"> 
<Name>Lee</Name> 
<Phone type="home">555-1212</Phone> 
<Phone type="work">555-1213</Phone> 
</Person> 
<Person contactType="Business"> 
<Name>Ariel</Name> 
<Phone>555-1234</Phone> 
</Person> 
</AddressBook> 
"@ 


PowerShell exposes all child nodes and attributes as properties. When it does this, PowerShell automatically groups children that share the same 
node type: 


SmyXml .AddressBook 


returns an object that contains a Per son property. 
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SmyXml1 .AddressBook. Person 


returns a list of Person nodes. Each person node exposes contactType, Name, and Phone as properties. 
SmyXml .AddressBook. Person [0] 

returns the first Person node. 
SmyxXml .AddressBook. Person [0] .ContactType 


returns Personal as the contact type of the first Person node. 


Simple Operators 
Once you have defined your data, the next step is to work with it. 


Arithmetic Operators 
The arithmetic operators let you perform mathematical operations on your data, as shown in Table 1-5. 


NOTE 


The System.Math class in the .NET Framework offers many powerful operations in addition to the native operators supported by 
PowerShell: 


PS > [Math]::Pow([Math]::E, [Math] ::Pi) 
23.1406926327793 


See “Working with the .NET Framework” to learn more about using PowerShell to interact with the .NET Framework. 


Table 1-5. PowerShell arithmetic operators 


Oper Meaning 
ator 


+ The addition operator: 


SleftValue + SrightValue 


When used with numbers, returns their sum. 
When used with strings, returns a new string created by appending the second string to the first. 
When used with arrays, returns a new array created by appending the second array to the first. 


When used with hashtables, returns a new hashtable created by merging the two hashtables. Since hashtable keys must be unique, PowerShell returns an 
error if the second hashtable includes any keys already defined in the first hashtable. 


When used with any other type, PowerShell uses that type’s addition operator (op_Addition) ifit implements one. 
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Oper Meaning 
ator 


= The subtraction operator: 


SleftValue - SrightValue 


When used with numbers, returns their difference. 
This operator does not apply to strings, arrays, or hashtables. 


When used with any other type, PowerShell uses that type’s subtraction operator (op Subtraction) if it implements one. 


a The multiplication operator: 


SleftValue * SrightValue 


When used with numbers, returns their product. 

When used with strings ("=""_* 80), returns a new string created by appending the string to itself the number of times you specify. 
When used with arrays (1..3 * 7), returns a new array created by appending the array to itself the number of times you specify. 
This operator does not apply to hashtables. 


When used with any other type, PowerShell uses that type’s multiplication operator (op_Multip1y) ifit implements one. 


/ The division operator: 


SleftValue / SrightValue 


When used with numbers, returns their quotient. 
This operator does not apply to strings, arrays, or hashtables. 


When used with any other type, PowerShell uses that type’s division operator (op Division) if it implements one. 
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Oper Meaning 
ator 
% The modulus operator: 


SleftValue % $rightValue 


When used with numbers, returns the remainder of their division. 


This operator does not apply to strings, arrays, or hashtables. 


When used with any other type, PowerShell uses that type’s modulus operator (op_Modulus) if it implements one. 


a= Assignment operators: 


= Svariable operator= value 


These operators match the simple arithmetic operators (+, —, *, /, and %) but store the result in the variable on the lefthand side of the operator. It is a 
short form for 


Svariable = Svariable operator value. 


Logical Operators 
The logical operators let you compare Boolean values, as shown in Table 1-6. 


Table 1-6. PowerShell logical operators 
Operator Meaning 


-and Logical AND: 


SleftValue -and SrightValue 


Returns $true ifboth lefthand and righthand arguments evaluate to $true. Returns $false otherwise. 
You can combine several -and operators in the same expression: 


Svaluel -and $value? -and $value3... 


PowerShell implements the -and operator as a short-circuit operator and evaluates arguments only ifall arguments preceding it evaluate to $true. 
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Operator Meaning 


or Logical OR: 


SleftValue -or $rightValue 


Returns $true ifthe lefthand or righthand arguments evaluate to $true. Returns $false otherwise. 
You can combine several -or operators in the same expression: 


Svaluel -or $value2 -or $value3 ... 


PowerShell implements the -or operator as a short-circuit operator and evaluates arguments only if all arguments preceding it evaluate to $false. 


-xor Logical exclusive OR: 


$leftValue -xor $rightValue 


Returns $true if either the lefthand or righthand argument evaluates to St rue, but not if both do. 


Returns $false otherwise. 


-not Logical NOT: 


I -not $value 


Returns $true ifits righthand (and only) argument evaluates to $false. Returns $false otherwise. 


Binary Operators 


The binary operators, listed in Table 1-7, let you apply the Boolean logical operators bit by bit to the operator’s arguments. When comparing 
bits, a 1 represents $t rue, whereas a 0 represents $ false. 


Table 1-7. PowerShell binary operators 


Operat Meaning 
or 
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Operat Meaning 
or 


-band Binary AND: 


SleftValue -band SrightValue 


Returns a number where bits are set to 1 ifthe bits of the lefthand and righthand arguments at that position are both 1. All other bits are set to 0. For 
example: 


PS > $intl = 0b110110110 

PS > $int2 = 0b010010010 

PS > $result = $intl -band $int2 

PS > [Convert]::ToString(Sresult, 2) 
10010010 


-bor Binary OR: 


SleftValue -bor $rightValue 


Returns a number where bits are set to 1 if either of the bits of the lefthand and righthand arguments at that position is 1. All other bits are set to 0. For 
example: 


PS > Sinti = Obl 0L10110 

PS > $int2 = 0b010010010 

PS > Sresult = Sintel -bor $int2 

PS > [Convert]::ToString(Sresult, 2) 
110110110 


-bxor Binary exclusive OR: 


SleftValue -—bxor SrightValue 


Returns a number where bits are set to 1 if either of the bits of the lefthand and righthand arguments at that position is 1, but not if both are. All other 
bits are set to 0. For example: 


PS > $int1 = 06110110110 

PS > $int2 = 0b010010010 

PS > $result = Sintl -bxor Sint2 

PS > [Convert]::ToString(Sresult, 2) 
100100100 
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Operat Meaning 
or 


-bnot Binary NOT: 


-bnot $value 


Returns a number where bits are set to 1 ifthe bit of the righthand (and only) argument at that position is set to 1. All other bits are set to 0. For 
example: 


PS > Sintl = 0pr10II0rI0 

PS > $result = -bnot $int1l 

PS > [Convert] ::ToString ($result, 2) 
IALILTLLIIALITILIILLITILTOOLOOL0QOL 


-shl Binary shifi left: 


$value -slh $count 


Shifts the bits ofa number to the left $count places. Bits on the righthand side are set to 0. For example: 


PS > $int1 = 438 

PS > [Convert]::ToString(Sintl, 2) 
110110110 

PS > $result = $intl -shl 5 


PS > [Convert]::ToString(Sresult, 2) 
11011011000000 


-shr Binary shift right: 


$value -slr $count 


Shifts the bits ofa number to the right $count places. For signed values, bits on the lefthand side have their sign preserved. For example: 


PS > Santl = -2345 

PS > [Convert]::ToString(Sintl, 2) 
TLIETT ETT bieaL ie) TOITLTOVOTEL 
PS > $result = $intl -shr 3 


PS > [Convert]::ToString($Sresult, 2) 
IEVA ILTA TTOITOLTOTO 


Other Operators 
PowerShell supports several other simple operators, as listed here. 


-replace (Replace operator) 


The replace operator returns a new string, where the text in "target" that matches the regular expression "pat tern" has been 
replaced with the replacement text "replacement": 
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"target" -replace "pattern", "replacement" 


The following returns a new string, where the text in "target" that matches the regular expression "pat tern" has been replaced with 
the output value of the script block supplied. In the script block, the $_ variable represents the current 


System. Text.RegularExpressions.Match: 


"target" -replace "pattern", { scriptblock } 


By default, PowerShell performs a case-insensitive comparison. The -i replace operator makes this case-insensitivity explicit, whereas the 
-creplace operator performs a case-sensitive comparison. 


If the regular expression pattern contains named captures or capture groups, the replacement string may reference those as well. For example: 


PS > "Hello World" -replace "(.*) (.*)",'S2 $1! 
World Hello 


If "target" represents an array, the - replace operator operates on each element of that array. 


For more information on the details of regular expressions, see Chapter 2. 


-f (Format operator) 


The format operator returns a string where the format items in the format string have been replaced with the text equivalent of the values in the 
value array: 


"Format String" -f values 


For example: 


PS > "{O:n0}" -f£ 1000000000 
1,000,000, 000 


The format string for the format operator is exactly the format string supported by the NET String. Format method. 
For more details about the syntax of the format string, see Chapter 4. 


-as (Type conversion operator) 


The type conversion operator returns $value cast to the given .NET type: 
Svalue -as [Type] 
If this conversion is not possible, PowerShell returns $nu11. For example: 


PS > 3/2 -as [int] 

2 

PS > Sresult = "Hello" -as [int] 
PS > $result -eq $null 

True 


-split (Split operator) 
The unary split operator breaks the given input string into an array, using whitespace (\ s +) to identify the boundary between elements: 


-split "Input String" 
It also trims the results. For example: 


PS > -split " Hello World " 
Hello 
World 


The binary split operator breaks the given input string into an array, using the given delimiteror script block to identify the 
boundary between elements: 
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"Input String" -split "delimiter", maximum, options 
"Input String" -split { Scriptblock },maximum 


Delimiter is interpreted as a regular expression match. Scriptblock is called for each character in the input, and a split is introduced 
when it returns $t rue. 


Maximum defines the maximum number of elements to be returned, leaving unsplit elements as the last item. This item is optional. Use "0" for 
unlimited if you want to provide options but not alter the maximum. 


Options define special behavior to apply to the splitting behavior. The possible enumeration values are: 
SimpleMatch 
Split on literal strings, rather than regular expressions they may represent. 


RegexMatch 
Split on regular expressions. This option is the default. 


CultureInvariant 


Does not use culture-specific capitalization rules when doing a case-isensitive split. 


IgnorePatternWhitespace 


Ignores spaces and regular expression comments in the split pattern. 


Multiline 
Allows the ^ and $ characters to match line boundaries, not just the beginning and end of the content. 


Singleline 


Treats the * and $ characters as the beginning and end of the content. This option is the default. 


IgnoreCase 


Ignores the capitalization of the content when searching for matches. 


ExplicitCapture 


Ina regular expression match, only captures named groups. This option has no impact on the -split operator. 
For example: 


PS > "1a2B3" -split "[a-z]+",0,"IgnoreCase" 
1 
2 
3 


-join (Join operator) 


The unary join operator combines the supplied items into a single string, using no separator: 
-join ("item1l","item2",...,"item_n") 
For example: 


PS > -join (“a;b 
ab 


The binary join operator combines the supplied items into a single string, using De 1 imi ter as the separator: 


("item1","item2",...,"item_n") -join Delimiter 
For example: 
PS > ("a", "b") -join m n" 


a, b 
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Comparison Operators 


The PowerShell comparison operators, listed in Table 1-8, let you compare expressions against each other. By default, PowerShell’s 
comparison operators are case-insensitive. For all operators where case sensitivity applies, the - i prefix makes this case insensitivity explicit, 
whereas the -c prefix performs a case-sensitive comparison. 


Table 1-8. PowerShell comparison operators 


Opera Meaning 
tor 


-eq The equality operator: 


$leftValue -eq $rightValue 


For all primitive types, returns Strue if SleftValueand SrightValueare equal. 


When used with arrays, returns all elements in 
SleftValue that are equal to SrightValue. 


When used with any other type, PowerShell uses that type’s Equals () method if it implements one. 


-ne The negated equality operator: 


$leftValue -ne $rightValue 


For all primitive types, returns $true ifSleftValueand SrightValueare not equal. 


When used with arrays, returns all elements in 
$leftValue that are not equal to SrightValue. 


When used with any other type, PowerShell returns the negation of that type’s Equals () method if it implements one. 


-ge The greater-than-or-equal operator: 


$leftValue -ge $rightValue 


For all primitive types, returns $true if $1eftValueis greater than or equal to $rightValue. 


When used with arrays, returns all elements in 
$leftValuethat are greater than or equal to 
SrightValue. 


When used with any other type, PowerShell returns the result of that object’s Compare () method if it implements one. If the method returns a number 
greater than or equal to zero, the operator returns $true. 
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Opera Meaning 
tor 


=gt The greater-than operator: 


$leftValue -gt $rightValue 


For all primitive types, returns $true if $1eftValueis greater than $rightValue. 


When used with arrays, returns all elements in 
$leftValuethat are greater than SrightValue. 


When used with any other type, PowerShell returns the result of that object’s Compare () method if it implements one. If the method returns a number 
greater than zero, the operator returns $t rue. 


-in The in operator: 


$value -in $list 


Returns $true ifthe value $value is contained in the list $ list. That is, ifSitem -eq $value returns Strue for at least one itemin the list. This is 
equivalent to the 
-contains operator with the operands reversed. 


= The negated in operator: 


notin 


Returns $t rue when the -in operator would return $false. 


-1t The /ess-than operator: 


SleftValue -lt SrightValue 


For all primitive types, returns Strue if SleftValueis less than SrightValue. 


When used with arrays, returns all elements in 
SleftValue that are less than SrightValue. 


When used with any other type, PowerShell returns the result of that object’s Compare () method if it implements one. If the method returns a number 
less than zero, the operator returns $true. 
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Opera Meaning 
tor 


-le The /ess-than-or-equal operator: 


SleftValue -le $rightValue 


For all primitive types, returns St rue if $leftValueis less than or equal to SrightValue. 


When used with arrays, returns all elements in 
SleftValue that are less than or equal to 
SrightValue. 


When used with any other type, PowerShell returns the result of that object’s Compare () method if it implements one. If the method returns a number 
less than or equal to zero, the operator returns $t rue. 


-like The like operator: 


SleftValue -like Pattern 


Evaluates the pattern against the target, returning $true ifthe simple match is successful. 


When used with arrays, returns all elements in 
SleftValue that match Pattern. 


The -like operator supports the following simple wildcard characters: 


?: Any single unspecified character 


*: Zero or more unspecified characters 


[a-b]: Any character in the range of a-b 


[ab]: The specified characters a or b 


For example: 


PS > "Test" -like "[A-Z]le?[tr]" 
True 
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Opera Meaning 


tor 
= The negated like operator: 
notli 
ke 
Returns $true when the -like operator would return $false. 
= The match operator: 
match 
"Target" -match Regular Expression 
Evaluates the regular expression against the target, returning $true ifthe match is successful. Once complete, PowerShell places the successful 
matches in the $matches variable. 
When used with arrays, returns all elements in Target that match Regular Expression. 
The $matches variable is a hashtable that maps the individual matches to the text they match. 0 is the entire text of the match, 1 and on contain the text 
fromany unnamed captures in the regular expression, and string values contain the text from any named captures in the regular expression. 
For example: 
PS > "Hello World" -match "(.*) (.*)" 
True 
PS > Smatches [1] 
Hello 
For more information on the details of regular expressions, see Chapter 2. 
= The negated match operator: 
notma 
tch 
Returns $true when the -match operator would return $false. 
The -notmatch operator still populates the Smatches variable with the results of match. 
= The contains operator: 
onta 
ins 
$list -contains $value 
Returns $true ifthe list specified by $ list contains the value $value—that is, if $item -eq $value returns $true for at least one itemin the list. 
This is equivalent to the -in operator with the operands reversed. 
= The negated contains operator: 
notco 
ntain 
s 


Returns $true when the -contains operator would return $false. 
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‘Opera Meaning 
tor 


-is The type operator: 


SleftValue -is [type] 


Returns Strue if $value is (or extends) the specified NET type. 


- The negated type operator: 
isnot 


Returns $true when the -is operator would return $false. 


Conditional Statements 
Conditional statements in PowerShell let you change the flow of execution in your script. 


if, elseif, and else Statements 


if (condition) 
statement block 
elseif (condition) 
statement block 
else 


statement block 


If condition evaluates to $t rue, PowerShell executes the statement block you provide. Then, it resumes execution at the end of the 
if/elseif/else statement list. PowerShell requires the enclosing braces around the statement block, even if the statement block contains 


only one statement. 


NOTE 


See “Simple Operators” and “Comparison Operators” for discussion on how PowerShell evaluates expressions as conditions. 


If condition evaluates to $ false, PowerShell evaluates any following (optional) e 1 sei £ conditions until one matches. If one matches, 
PowerShell executes the statement block associated with that condition, and then resumes execution at the end ofthe if /elseif/else 


statement list. 
For example: 


StextToMatch = Read-Host "Enter some text" 

SmatchType = Read-Host "Apply Simple or Regex matching?" 
Spattern = Read-Host "Match pattern" 

if(SmatchType -eq "Simple") 


StextToMatch -like $pattern 
elseif ($matchType -eq "Regex") 
StextToMatch -match $pattern 


else 


Write-Host "Match type must be Simple or Regex" 
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Ifnone of the conditions evaluate to $t rue, PowerShell executes the statement block associated with the (optional) e 1 se clause, and then 
resumes execution at the end ofthe if /elseif/else statement list. 


To apply an if statement to each element ofa list and filter it to return only the results that match the supplied condition, use the Whe re- 
Object cmdlet or . where () method: 


Get-Process | Where-Object { $ .Handles -gt 500 } 


(Get-Process) .where( { $ .Handles -gt 500} ) 


Ternary Operators 


Sresult = condition ? true value : false value 


A short-form version ofan iffelse statement. If condition evaluates to $t rue, the result of the expression is the value of the true value 
clause. Otherwise, the result of the expression is the value of the false value clause. For example: 


(Get-Random) % 2 -eq 0 ? "Even number" : "Odd number" 


Null Coalescing and Assignment Operators 


Sresult = nullable value ?? default value 


Assignment version: 


Sresult = nullable value 
Sresult ??= default value 


A short-form version ofa ternary operator that only checks if the expression is null or not. If it is null, the result of the expression is the value of 
the default value clause. For example: 


Get-Process | ForEach-Object { $ .CPU ?? "<Unavailable>" } 
or 


Scpu = (Get-Process -id 0) .CPU 
Scpu ??= "Unavailable" 


switch Statements 


switch options expression 

{ 
comparison value { statement block } 
-or- 
{ comparison expression } { statement block } 
Gerace) 
default { statement block } 


or: 


switch options -file filename 

{ 
comparison value { statement block } 
-or 
{ comparison expression } { statement block } 
(..-) 
default { statement block } 


When PowerShell evaluates a switch statement, it evaluates expression against the statements in the switch body. If expressions 
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a list of values, PowerShell evaluates each item against the statements in the switch body. If you specify the -fi Le option, PowerShell treats 
the lines in the file as though they were a list ofitems in expression. 


The comparison value statements let you match the current input item against the pattern specified by comparison value. By 
default, PowerShell treats this as a case-insensitive exact match, but the options you provide to the switch statement can change this, as 
shown in Table 1-9. 


Option 


casesensitive 


-exact 


-regex 


-wildcard 


Table 1-9. Options supported by PowerShell switch statements 


Meaning 


Case-sensitive match. 


With this option active, PowerShell executes the associated statement block only ifthe current input item exactly matches the value specified 
by 
comparison value. Ifthe current input object is a string, the match is case-sensitive. 


Exact match 


With this option active, PowerShell executes the associated statement block only ifthe current input item exactly matches the value specified 
by 
comparison value. This match is case-insensitive. This is the default mode of operation. 


Regular-expression match 


With this option active, PowerShell executes the associated statement block only if the current input item matches the regular expression 
specified by 
comparison value. This match is case-insensitive. 


Wildcard match 


With this option active, PowerShell executes the associated statement block only if the current input item matches the wildcard specified by 
comparison value. 


The wildcard match supports the following simple wildcard characters: 


?: Any single unspecified character 


*: Zero or more unspecified characters 


[a-b]: Any character in the range of a-b 


[ab]: The specified characters a or b 


This match is case-insensitive. 


The { comparison expression } statements let you process the current input item, which is stored inthe $_ (or SPSItem) 
variable, in an arbitrary script block. When it processes a { comparison expression } statement, PowerShell executes the 


29 
associated statement block only if { comparison expression } evaluates to Strue. 
PowerShell executes the statement block associated with the (optional) de fault statement ifno other statements in the switch body 
match. 


When processing a switch statement, PowerShell tries to match the current input object against each statement in the switch body, falling 
through to the next statement even after one or more have already matched. To have PowerShell discontinue the current comparison (but retry 
the switch statement with the next input object), include a continue statement as the last statement in the statement block. To have 
PowerShell exit a switch statement completely after it processes a match, include a break statement as the last statement in the statement 
block. 


For example: 


SmyPhones = "(555) 555-1212","555-1234" 


switch -regex (SmyPhones) 

{ 
{ $_.Length -le 8 } { "Area code was not specified"; break } 
{ $_.Length -gt 8 } { "Area code was specified" } 
Wh (GSS) AD a { "In the $(Smatches[1]) area code" } 

} 


produces the output: 


Area code was specified 
In the 555 area code 
Area code was not specified 


NOTE 


See the next section on Looping Statements for more information about the break statement. 


By default, PowerShell treats this as a case-insensitive exact match, but the options you provide to the switch statement can change this. 


Looping Statements 
Looping statements in PowerShell let you execute groups of statements multiple times. 


for Statement 


:loop_ label for (initialization; condition; increment) 


{ 


statement block 


} 


When PowerShell executes a for statement, it first executes the expression given by initialization. It next evaluates condition. 
If condition evaluates to $t rue, PowerShell executes the given statement block. It then executes the expression given by 
increment. PowerShell continues to execute the statement block and increment statement as long as condition evaluates to 
Strue. 


For example: 


for (Scounter = 0; $counter -lt 10; Scounter++) 


{ 


Write-Host "Processing item Scounter" 


} 


The break and continue statements (discussed in “Flow Control Statements”) can specify the Loop_labe1 ofany enclosing looping 
statement as their target. 


foreach Statement 


:loop_label foreach(variable in expression) 


{ 
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statement block 


When PowerShell executes a foreach statement, it executes the pipeline given by expression—for example, Get-Process | 
Where-Object {$ .Handles -gt 500} or1..10. For each item produced by the expression, it assigns that item to the 
variable specified by variable and then executes the given statement block. For example: 


ShandleSum = 0 
foreach (Sprocess in Get-Process | 
Where-Object { $ .Handles -gt 500 }) 
{ 
ShandleSum += Sprocess.Handles 
} 
ShandleSum 


In addition to the foreach statement, you can also use the fo reach method on collections directly: 


ShandleSum = 0 
(Get-Process) .foreach( { $handleSum += $ .Handles } ) 


The break and continue statements (discussed in “Flow Control Statements”) can specify the loop_labe1 ofany enclosing looping 
statement as their target. In addition to the fo reach statement, PowerShell also offers the ForEach-Object cmdlet with similar 
capabilities. 


while Statement 


:loop label while (condition) 


{ 


statement block 


} 


When PowerShell executes a while statement, it first evaluates the expression given by condi tion. Ifthis expression evaluates to 
$true, PowerShell executes the given statement block. PowerShell continues to execute the statement block as longas condition 
evaluates to $t rue. For example: 


Scommand = ""; 
while (Scommand -notmatch "quit") 


{ 


Scommand = Read-Host "Enter your command" 


} 


The break and continue statements (discussed in “Flow Control Statements”) can specify the Loop_labe1 ofany enclosing looping 
statement as their target. 


do ... while Statement/do ... until Statement 


:loop_label do 
{ 


statement block 
} while (condition) 


or 


:loop_label do 
{ 

statement block 
} until (condition) 


When PowerShell executes ado ... while ordo .. until statement, it first executes the given statement block. Ina do .. while 
statement, PowerShell continues to execute the statement block as long as condition evaluates to Strue.Inado ... until 
statement, PowerShell continues to execute the statement as long as condition evaluates to $ false. For example: 


SvalidResponses = "Yes","No" 
Sresponse = "™" 
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do 


{ 

Sresponse = Read-Host "Yes or No?" 
} while (SvalidResponses -notcontains S$response) 
"Got Sresponse" 


Sresponse = ™ 
do 
{ 


Sresponse = Read-Host "Yes or No?" 
} until (SvalidResponses -contains S$response) 
"Got Sresponse" 


The break and continue statements (discussed in the next section) can specify the loop_labe1 ofany enclosing looping statement as 
their target. 


Flow Control Statements 
PowerShell supports two statements to help you control flow within loops: break and continue. 


break 


The break statement halts execution of the current loop. PowerShell then resumes execution at the end of the current looping statement, as 
though the looping statement had completed naturally. For example: 


for (Scounter = 0; Scounter -lt 5; Scounter++) 
{ 
for (Scounter2 = 0; S$counter2 -lt 5; Scounter2++) 
{ 
if (Scounter2 -eq 2) 
{ 
break 
} 


Write-Host "Processing item $counter, $counter2" 


produces the output (notice the second column never reaches the value 2): 


Processing item 0,0 
Processing item 0,1 
Processing item 1,0 
Processing item 1,1 
Processing item 2,0 
Processing item 2,1 
Processing item 3,0 
Processing item 3,1 
Processing item 4,0 
Processing item 4,1 


If you specify a label with the break statement—for example, break outer _1loop—PowerShell halts the execution of that loop 
instead. For example: 


:outer loop for (Scounter = 0; Scounter -lt 5; $counter++) 
{ 
for (Scounter2 = 0; Scounter2 -lt 5; Scounter2++) 
{ 
if (Scounter2 -eq 2) 
{ 


break outer loop 


} 


Write-Host "Processing item $counter, $counter2" 


produces the output: 


Processing item 0,0 
Processing item 0,1 
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continue 


The continue statement skips execution of the rest of the current statement block. PowerShell then continues with the next iteration of the 
current looping statement, as though the statement block had completed naturally. For example: 


for (Scounter = 0; $counter -lt 5; Scounter++) 


{ 


for (Scounter2 = 0; Scounter2 -lt 5; Scounter2++) 


{ 
if (Scounter2 -eq 2) 


{ 


continue 


} 


Write-Host "Processing item Scounter, Scounter2" 


produces the output: 
Processing item 0,0 
Processing item 0,1 
Processing item 0,3 
Processing item 0,4 
Processing item 1,0 
Processing item 1,1 
Processing item 1,3 
Processing item 1,4 
Processing item 2,0 
Processing item 2,1 
Processing item 2,3 
Processing item 2,4 
Processing item 3,0 
Processing item 3,1 
Processing item 3,3 
Processing item 3,4 
Processing item 4,0 
Processing item 4,1 
Processing item 4,3 
Processing item 4,4 


If you specify a label with the continue statement—for example, continue outer 1loop—PowerShell continues with the next 
iteration of that loop instead. 


For example: 


:outer loop for (Scounter = 0; Scounter -lt 5; $counter++) 


{ 


for (Scounter2 = 0; S$counter2 -lt 5; Scounter2++) 
{ 

if (Scounter2 -eq 2) 

{ 


continue outer loop 


} 


Write-Host "Processing item $counter, $counter2" 


produces the output: 
Processing item 0,0 
Processing item 0,1 
Processing item 1,0 
Processing item 1,1 
Processing item 2,0 
Processing item 2,1 
Processing item 3,0 
Processing item 3,1 
Processing item 4,0 
Processing item 4,1 
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Classes 


## A class called "Example" that inherits from "BaseClass" 
## and implements the "ImplementedInterface" interface 
class Example : BaseClass, ImplementedInterfac 


{ 


## Default constructor, which also invokes the constructor 
## from the base class. 
Example() : base() 


{ 


[Example]::lastInstantiated = Get-Date 


} 


## Constructor with parameters 
Example ( [string] $Name) 


Sthis.Name = $Name 
Example]::lastInstantiated = Get-—Date 


## A publicly visible property with validation attributes 
ValidateLength (2,20) ] 
string] $Name 


## A property that is hidden from default views 
static hidden [DateTime] SlastInstantiated 


## A publicly visible method that returns a value 

[string] ToString() 

{ 
## Return statement is required. Implicit / pipeline output 
## is not treated as output like it is with functions. 
return Sthis.ToString( [Int32]::MaxValue ) 

} 


## A publicly visible method that returns a value 
[string] ToString([int] $MaxLength) 
{ 
$output = "Name = $(S$this.Name) ;" 
"LastInstantiated = $([Example]::lastInstantiated)" 
SoutputLength = [Math]::Min(SMaxLength, Soutput.Length) 
return Soutput.Substring(0, SoutputLength) 


Base classes and interfaces 


To define a class that inherits froma base class or implements an interfaces, provide the base class and/or interface names after the class name, 
separated by a colon (deriving ftom a base class or implementing any interfaces is optional): 


class Example [: BaseClass, ImplementedInterface] 


Constructors 


To define a class constructor, create a method with the same name as the class. You can define several constructors, including those with 
parameters. To automatically call a constructor from the base class, add : base () to the end of the method name: 


Example() [: base()] 
Example ([int] SParameterl, [string] S$Parameter2) [: base()] 
Properties 


To define a publicly visible property, define a PowerShell variable in your class. As with regular Powershell variables, you may optionally add 
validation attributes or declare a type constraint for the property: 


[ValidateLength (2,20) ] 
[string] $Name 


To hide the property from default views (similar to a member variable in other languages), use the hidden keyword. Users are still able to 
access hidden properties if desired: they are just removed from default views. You can make a property st at ic ifyou want it to be shared 
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with all instances of your class in the current process: 


static hidden [DateTime] SlastInstantiated 


Methods 


Define a method as though you would define a PowerShell function, but without the function keyword and without the param () statement. 
Methods support parameters, parameter validation, and can also have the same name as long as their parameters differ: 


[string] ToString() { ... } 


[string] ToString([int] $MaxLength) { ... } 


Custom Enumerations 


To define a custom enumeration, use the enum keyword: 


enum MyColor { 
Red = 1 
Green = 2 
Blue = 3 

} 


If enumeration values are intended to be combined through bitwise operators, use the [Flags () ] attribute. Ifyou require that the 
enumerated values derive froma specific integral data type (byte, sbyte, short, ushort, int, uint, long or ulong), provide that data type after the 
colon character: 


[Flags()] enum MyColor : uint { 
Red = 1 
Green = 2 
Blue = 4 


Workflow-Specific Statements 


Within a workflow, PowerShell supports three statements not supported in traditional PowerShell scripts: InineScript, Parallel, 
and Sequence. 


NOTE 


Workflows are no longer supported in PowerShell. This section exists to help you understand and interact with workflows that have 
already been written. 


InlineScript 


The InlineScript keyword defines an island of PowerShell script that will be invoked as a unit, and with traditional PowerShell scripting 
semantics. For example: 


workflow MyWorkflow 

{ 
## Method invocation not supported in a workflow 
## [Math] ::Sqrt (100) 


InlineScript 


{ 
## Supported in an InlineScript 
[Math] ::Sqrt (100) 


Parallel/Sequence 


The Parallel keyword specifies that all statements within the statement block should run in parallel. To group statements that should be run 
as a unit, use the Sequence keyword: 


workflow MyWorkflow 
{ 
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Parallel 


{ 
InlineScript { Start-Sleep -Seconds 2; 
"One thing run in parallel" } 
InlineScript { Start-Sleep -Seconds 4 
"Another thing run in parallel" } 
InlineScript { Start-Sleep -Seconds 3; 
"A third thing run in parallel" } 


Sequence 
{ 
Start-Sleep -Seconds 1 
"A fourth"™ 
"and fifth thing run as a unit, in parallel" 


Note that you should not use PowerShell Workflows for the parallel statement alone—the -Parallel parameter to the ForEach- 
Object cmdkt is much more efficient. 


Working with the .NET Framework 


One feature that gives PowerShell its incredible reach into both system administration and application development is its capability to leverage 
Microsoft’s enormous and broad .NET Framework. 


Working with the .NET Framework in PowerShell comes mainly by way of one of two tasks: calling methods or accessing properties. 


Static Methods 
To call a static method on a class, type: 


[ClassName] ::MethodName (parameter list) 
For example: 
PS > [System.Diagnostics. Process] ::GetProcessById (0) 
gets the process with the ID of 0 and displays the following output: 
Handles NPM(K) PM (K) WS (K) VM(M) CPU(s) Id ProcessName 


Instance Methods 


To call a method on an instance of an object, type: 
SobjectReference.MethodName (parameter list) 


For example: 


PS > Sprocess = [System.Diagnostics. Process] ::GetProcessById (0) 
PS > Sprocess.Refresh () 


This stores the process with ID of 0 into the $process variable. It then calls the Re fresh () instance method on that specific process. 


Explicitly Implemented Interface Methods 
To call a method on an explictly implemented interface, type: 


({Interface] SobjectReference) .MethodName (parameter list) 
For example: 


PS > ([{IConvertible] 123) .ToUint16 ($null) 


Static Properties Á 
To access a static property on a class, type: 
[ClassName] : : PropertyName 
or: 
[ClassName] : : PropertyName = value 


For example, the [System.DateTime] class provides a Now static property that returns the current time: 


PS > [System.DateTime] : :Now 
Sunday, July 16, 2006 2:07:20 PM 


Although this is rare, some types let you set the value of some static properties. 


Instance Properties 


To access an instance property on an object, type: 
SobjectReference. PropertyName 
or: 


SobjectReference. PropertyName = valu 


For example: 


PS > Stoday = [System.DateTime] : :Now 
PS > Stoday.DayOfWeek 
Sunday 


This stores the current date in the $ today variable. It then calls the Da yO Week instance property on that specific date. 


If the value of the property might be null, you can use the null conditional property access operator (? . ). The result of the expression will be 
null if any property in the chain did not exist. It will be the final property’s value otherwise: 


(Get-Process -id 0) ?.MainModule?.Filename 


Learning About Types 
The two primary avenues for learning about classes and types are the Get -Membe r cmdket and the documentation for the NET Framework. 


The Get-Member cmdlet 
To learn what methods and properties a given type supports, pass it through the Get -Membe r cmdket, as shown in Table 1-10. 


Table 1-10. Working with the Get-Member cmdlet 


Action Result 

[typename] | Allthe static methods and properties ofa given type. 
Get-Member- 

Static 


SobjectReferenc Allthe static methods and properties provided by the type in SobjectReference. 
e| 

Get-Member- 

Static 
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Action Result 


SobjectReferenc Allthe instance methods and properties provided by the type in SobjectReference. If 

e|Get-Member SobjectReference represents a collection of items, PowerShell returns the instances and properties of the types contained by that 
collection. To view the instances and properties ofa collection itself, use the -InputObject parameter of 
Get-Member: 


Get-Member -—InputObject SabjectReference 


[typename] | All the instance methods and properties ofa 
Get-Member System. RuntimeType object that represents this type. 


.NET Framework documentation 


Another source of mformation about the classes in the NET Framework is the documentation itself, available through the search facilities at 
Microsoft’s developer documentation site. 


Typical documentation for a class first starts with a general overview, and then provides a hyperlink to the members of the class—the list of 
methods and properties it supports. 


NOTE 


To get to the documentation for the members quickly, search for them more explicitly by adding the term “members” to your search term: 


classname members 


The documentation for the members ofa class lists their constructors, methods, properties, and more. It uses an S icon to represent the static 
methods and properties. Click the member name for more information about that member, including the type of object that the member 
produces. 


Type Shortcuts 


When you specify a type name, PowerShell lets you use a short form for some of the most common types, as listed in Table 1-11. 


Table 1-11. PowerShell type shortcuts 


Type shortcut Full classname 
Adsi] System. DirectoryServices.DirectoryEntry] 
AdsiSearcher] System. DirectoryServices.DirectorySearcher] 
Float] System. Single] 
Hashtable] System.Collections.Hashtable] 
Int] System. Int32] 
IPAddress] System.Net.IPAddress 
Long] System.Collections.Int64 
PowerShell] System.Management.Automation. PowerShell] 
PSCustomObject ] System.Management.Automation.PSObject] 
PSModuleInfo] System.Management.Automation.PSModuleInfo] 
PSObject] System.Management.Automation.PSObject] 
Ref] System.Management.Automation.PSReference] 
Regex] System. Text .RegularExpressions. Regex 
Runspace ] System.Management.Automation.Runspaces.Runspace] 
RunspaceFactory] [System.Management .Automation.Runspaces.RunspaceFactory] 
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Type shortcut Full classname 
ScriptBlock] System.Management.Automation.ScriptBlock] 
Switch] System.Management .Automation.SwitchParameter] 
Wmi] System.Management .ManagementObject] 
WmiClass] System.Management .ManagementClass] 
WmiSearcher] System.Management .ManagementObjectSearcher] 
Xml] System.Xml .XmlDocument] 
TypeName] System. TypeName] 


Creating Instances of Types 


SobjectReference = New-Object TypeName parameters 
SobjectReference = [TypeName] : :new (parameters) 


Although static methods and properties ofa class generate objects, you'll often want to create them explicitly yourself? PowerShell’s New- 
Object cmdlet lets you create an instance of the type you specify. The parameter list must match the list of parameters accepted by one of the 
type’s constructors, as described in the SDK documentation. 


For example: 


SwebClient = New-Object Net.WebClient 
SwebClient .DownloadString ("http://search.msn.com") 


If the type represents a generic type, enclose its type parameters in square brackets: 


PS > Shashtable = 
New-Object "System.Collections.Generic.Dictionary[String, Bool]" 
PS > Shashtable["Test"] = $tru 


Most common types are available by default. However, many types are available only after you load the library (called the assembly) that 
defines them. The Microsoft documentation for a class includes the assembly that defines it. 


To load an assembly, use the -Assemb1yName parameter of the Add-Type cmdlet: 
PS > Add-Type -AssemblyName System.Web 


PS > [System.Web.HttpUtility] ::UrlEncode ("http://www.bing.com") 
http%3as2£S2fwww.bing.com 


To update the list of namespaces that PowerShell searches by default, specify that namespace ina us ing statement: 


PS > using namespace System.Web 
PS > [HttpUtility] ::UrlEncode ("http://www.bing.com") 


Interacting with COM Objects 


PowerShell lets you access methods and properties on COM objects the same way you would interact with objects from the .NET 
Framework. To interact with a COM object, use its ProgId with the -ComObject parameter (often shortened to -Com) on New- 
Object: 


PS > Sshell = New-Object -Com Shell.Application 
PS > Sshell.Windows() | Select-Object LocationName, LocationUrl 


For more information about the COM objects most useful to system administrators, see Chapter 8. 


Extending Types 


PowerShell supports two ways to add your own methods and properties to any type: the Add-Member cmdlet and a custom types extension 
file. 


The Add-Member cmdlet 
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The Add-Member cmdket lets you dynamically add methods, properties, and more to an object. It supports the extensions shown in Table 1- 
12. 


Table 1-12. Selected member types supported by the Add-Member cmdlet 


Member type Meaning 


AliasProperty A property defined to alias another property: 


PS > StestObject = [PsObject] "Test" 
PS > StestObject 
Add-Member "AliasProperty" Count Length 
PS > StestObject.Count 
4 


CodeProperty A property defined by a System. Reflection.MethodInfo. 


This method must be public, static, return results (nonvoid), and take one parameter of type PsObject. 


NoteProperty A property defined by the initial value you provide: 


PS > StestObject = [PsObject] "Test" 
PS > StestObject 
Add-Member NoteProperty Reversed tseT 
PS > StestObject.Reversed 
tseT 


ScriptPropert A property defined by the script block you provide. In that script block, $this refers to the current instance: 
yY 


PS > $testObject = [PsObject] ("Hi" * 100) 
PS > $testObject | 
Add-Member ScriptProperty IsLong { 
Sthis.Length -gt 100 
} 
PS > $testObject.IsLong 


True 


PropertySet A property defined as a shortcut to a set of properties. Used in cmdlets such as Select-Object: 


PS > StestObject = [PsObject] [DateTime]::Now 
PS > Scollection = New-Object 
Collections.ObjectModel.Collection[String] 
Scollection.Add ("Month") 
Scollection.Add("Year" 
StestObject | 

Add-Member PropertySet MonthYear S$collection 
StestObject | select MonthYear 


Year 


3 2010 


CodeMethod A method defined by a System. Reflection.MethodInfo. 


This method must be public, static, and take one parameter of type 
PsObject 
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Member type Meaning 


ScriptMethod A method defined by the script block you provide. In that script block, $this refers to the current instance, and $args refers to the input 
parameters: 


PS > StestObject = [PsObject] "Hello" 
PS > S$testObject | 
Add-Member ScriptMethod IsLong { 
Sthis.Length -gt Sargs[0] 
} 
PS > $testObject.IsLong (3) 
True 


PS > StestObject.IsLong (100) 
False 


Custom type extension files 


While the Add-Membe r cmdket lets you customize individual objects, PowerShell also supports configuration files that let you customize all 
objects ofa given type. For example, you might want to add a Reverse () method to all strings or a He 1 pUr1 property (based on the 
documentation URLs) to all types. 


PowerShell adds several type extensions to the file types. ps 1xml, in the PowerShell installation directory. This file is useful as a source of 
examples, but you should not modify it directly. Instead, create a new one and use the Update-TypeData cmulet to load your 
customizations. The following command loads Types.custom.psixml from the same directory as your profile: 


StypesFile = Join-Path (Split-Path Sprofile) "Types.Custom.Ps1Xm1l" 
Update-TypeData -PrependPath S$typesFile 


Writing Scripts, Reusing Functionality 


When you want to start packaging and reusing your commands, the best place to put them is in scripts, functions, and script blocks. A script is 
a text file that contains a sequence of PowerShell commands. A function is also a sequence of PowerShell commands, but is usually placed 
within a script to break it into smaller, more easily understood segments. A script block is a function with no name. All three support the same 
functionality, except for how you define them 


Writing Commands 


Writing scripts 
To write a script, write your PowerShell commands in a text editor and save the file with a .ps/ extension. 


Writing functions 


Functions let you package blocks of closely related commands into a single unit that you can access by name: 


function SCOPE: name (parameters) 


{ 


statement block 


} 


or: 


filter SCOPE: name (parameters) 


{ 


statement block 


} 


Valid scope names are globa1 (to create a function available to the entire shell), script (to create a function available only to the current 
script), 1ocal (to create a function available only to the current scope and subscopes), and private (to create a function available only to 
the current scope). The default scope is the 1 ocal scope, which follows the same rules as those of default variable scopes. 


The content ofa fùnction’s statement block follows the same rules as the content ofa script. Functions support the $args array, formal 
parameters, the $input enumerator, cmdlet keywords, pipeline output, and equivalent return semantics. 
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NOTE 


A common mistake is to call a function as you would call a method: 
$result = GetMyResults(Siteml, $item2) 

PowerShell treats functions as it treats scripts and other commands, so this should instead be: 
$result = GetMyResults $iteml $item2 


The first command passes an array that contains the items $item1 and $item2 to the GetMyResults function. 


A filter is simply a function where the statements are treated as though they are contained within a process statement block. For more 
information about process statement blocks, see “Cmdlet keywords in commands”. 


NOTE 


Commands in your script can access only functions that have already been defined. This can often make large scripts difficult to 
understand when the beginning of the script is composed entirely of helper functions. Structuring a script in the following manner often 
makes it more clear: 


function Main 
Cae) 


HelperFunction 
Cece a) 


function HelperFunction 


. Main 


Writing script blocks 


SobjectReference = 


{ 


statement block 


} 


PowerShell supports script blocks, which act exactly like unnamed functions and scripts. Like both scripts and functions, the content ofa script 
block’s statement block follows the same rules as the content ofa function or script. Script blocks support the $args array, formal 
parameters, the $input enumerator, cmdlet keywords, pipeline output, and equivalent return semantics. 


As with both scripts and functions, you can either invoke or dot-source a script block. Since a script block does not have a name, you either 
invoke it directly (& {"Hel1o"}$) or invoke the variable (& S$objectReference) that contains it. 


Running Commands 
There are two ways to execute a command (script, function, or script block): by invoking it or by dot-sourcing it. 


Invoking 


Invoking a command runs the commands inside it. Unless explicitly defined with the GLOBAL scope keyword, variables and functions defined 
in the script do not persist once the script exits. 
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NOTE 


By default, a security feature in PowerShell called the Execution Policy prevents scripts from running. When you want to enable scripting 
in PowerShell, you must change this setting. To understand the different execution policies available to you, type Get-Help 
about_signing. After selecting an execution policy, use the Set-ExecutionPolicy cmdlet to configure it: 


Set-ExecutionPolicy RemoteSigned 


Ifthe command name has no spaces, simply type its name: 


c:\temp\Invoke-Commands.psl parameterl parameter? ... 
Invoke-MyFunction parameterl parameter2 ... 


To run the command as a background job, use the background operator («): 


c:\temp\Invoke-Commands.psl parameterl parameter2 ... & 


You can use either a filly qualified path or a path relative to the current location. If the script is in the current directory, you must explicitly say 
so: 


.\Invoke-Commands.ps1 parameterl parameter2 ... 


Ifthe command’s name has a space (or the command has no name, in the case ofa script block), you invoke the command by using the 
invoke/call operator (& ) with the command name as the parameter: 


& "C:\My Scripts\Invoke-Commands.ps1" parameterl parameter2 ... 
Script blocks have no name, so you place the variable holding them after the invocation operator: 


SscriptBlock = { "Hello World" } 
& SscriptBlock parameterl parameter2 ... 


If you want to invoke the command within the context ofa module, provide a reference to that module as part of the invocation: 


Smodule = Get-Module PowerShel1Cookbook 
& Smodule Invoke-MyFunction parameterl parameter2 ... 
& Smodule SscriptBlock parameterl parameter2 ... 


Dot-sourcing 


Dot-sourcing a command runs the commands inside it. Unlike simply invoking a command, variables and functions defined in the script do 
persist after the script exits. 


You invoke a script by using the dot operator (. ) and providing the command name as the parameter: 


"C:\Script Directory\Invoke-Commands.ps1" Parameters 
Invoke-MyFunction parameters 
SscriptBlock parameters 


When dot-sourcing a script, you can use either a filly qualified path or a path relative to the current location. If the script is in the current 
directory, you must explicitly say so: 


.\Invoke-Commands.ps1 Parameters 


If you want to dot-source the command within the context ofa module, provide a reference to that module as part of the invocation: 


Smodule = Get-Module PowerShel1Cookbook 
Smodule Invoke-MyFunction parameters 
Smodule SscriptBlock parameters 


Parameters 
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Commands that require or support user input do so through parameters. You can use the Get -Command cmdlet to see the parameters 


supported by a command: 


PS > Get-Command Stop-Process -Syntax 


Stop-Process [-Id] <int[]> [-PassThru] [-Force] [-WhatIf] [...] 
Stop-Process -Name <string[]> [-PassThru] [-Force] [-WhatIf] [...] 
Stop-Process [-InputObject] <Process[]> [-PassThru] [-Force] [... 


In this case, the supported parameters of the Stop-Process command are Id, Name, InputObject, PassThru, Force, 
WhatIf, and Confirm. 


To supply a value for a parameter, use a dash character, followed by the parameter name, followed by a space, and then the parameter value: 
Stop-Process -Id 1234 

Ifthe parameter value contains spaces, surround it with quotes: 
Stop-Process -Name "Process With Spaces" 

Ifa variable contains a value that you want to use for a parameter, supply that through PowerShell’s regular variable reference syntax: 


Sname = "Process With Spaces" 
Stop-Process -Name $name 


If you want to use other PowerShell language elements as a parameter value, surround the value with parentheses: 
Get-Process -Name ("Power" + "Shell") 

You only need to supply enough of the parameter name to disambiguate it from the rest of the parameters: 
Stop-Process -N "Process With Spaces" 


Ifa command’s syntax shows the parameter name in square brackets (such as [- Id] ), then it is positional and you may omit the parameter 
name and supply only the value. PowerShell supplies these unnamed values to parameters in the order of their position: 


Stop-Process 1234 
Rather than explicitly providing parameter names and values, you can provide a hashtable that defines them and use the splatting operator: 


Sparameters = @{ 
Path = "c:\tempo" 
Recurse = Strue 


} 


Get-ChildItem @parameters 


To define the default value to be used for the parameter ofa command (if the parameter value is not specified directly), assign a value to the 
PSDefaultParameterValues hashtable. The keys of this hashtable are command names and parameter names, separated by a colon. 
Either (or both) may use wildcards. The values of this hashtable are either simple parameter values, or script blocks that will be evaluated 


dynamically: 


PS > S$PSDefaultParameterValues ["Get-Process:ID"] = Spid 
PS > Get-Process 


PS > SPSDefaultParameterValues ["Get-Service:Name"] = { 
Get-Service -Name * | ForEKach-Object Name | Get-Random } 
PS > Get-Service 


Providing Input to Commands 


PowerShell offers several options for processing input to a command. 


Argument array 


To access the command-line arguments by position, use the argument array that PowerShell places in the $args special variable: 
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SfirstArgument = Sargs[0] 
SsecondArgument = Sargs[1] 
SargumentCount = Sargs.Count 


Formal parameters 


To define a command with simple parameter support: 


param ( 
[TypeName] SVariableName = Default, 


To define one with support for advanced functionality: 


[CmdletBinding(cmdlet behavior customizations) ] 
param ( 
[Parameter (Mandatory = Strue, Position = 1, ...)] 
[Alias ("MyParameterAlias"] 


PE 
[TypeName] SVariableName = Default, 


Formal parameters let you benefit from some of the many benefits of PowerShell’s consistent command-line parsing engine. 


PowerShell exposes your parameter names (for example, $VariableName) the same way that it exposes parameters in cmdlets. Users 
need to type only enough of your parameter name to disambiguate it from the rest of the parameters. 


If you define a command with simple parameter support, PowerShell attempts to assign the input to your parameters by their position if the user 
does not type parameter names. 


When you add the [CmdletBinding () ] attribute, [Parameter () ] attribute, or any of the validation attributes, PowerShell adds 
support for advanced parameter validation. 


Command behavior customizations 
The elements of the [CmdletBinding () ] attribute describe how your script or function interacts with the system: 


SupportsShouldProcess = Strue 


If$ true, enables the -what I f and -Con firm parameters, which tells the user that your command modifies the system and can be 
run in one of these experimental modes. When specified, you must also call the SpsCmdlet.ShouldProcess () method before 
modifying system state. When not specified, the default is $ false. 


DefaultParameterSetName = name 


Defines the default parameter set name of this command. This is used to resolve ambiguities when parameters declare multiple sets of 
parameters and the user input doesn’t supply enough information to pick between available parameter sets. When not specified, the 
command has no default parameter set name. 


ConfirmImpact ="High" 


Defines this command as one that should have its confirmation messages (generated by the SosCmdlet .ShouldProcess () 
method) shown by default. More specifically, PowerShell defines three confirmation impacts: Low, Medium, and High. PowerShell 
generates the cmdlet’s confirmation messages automatically whenever the cmdlet’s impact level is greater than the preference variable. 
When not specified, the command’s impact is Medium. 


Parameter attribute customizations 


The elements of the [Parameter () ] attribute mainly define how your parameter behaves mn relation to other parameters (all elements are 
optional): 


Mandatory = Strue 


Defines the parameter as mandatory. If the user doesn’t supply a value to this parameter, PowerShell automatically prompts him for it. 
When not specified, the parameter is optional. 


Position =position 


Defines the position of this parameter. This applies when the user provides parameter values without specifying the parameter they apply to 
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(e.g, Argument2 nInvoke-MyFunction -Paraml Argument1 Argument 2). PowerShell supplies these values to 


parameters that have defined a Position, ftom lowest to highest. When not specified, the name of this parameter must be supplied by 
the user. 


ParameterSetName =nam 


Defines this parameter as a member ofa set of other related parameters. Parameter behavior for this parameter is then specific to this 
related set of parameters, and the parameter exists only in the parameter sets that it is defined in. This feature is used, for example, when the 
user may supply only a Name or ID. To include a parameter in two or more specific parameter sets, use two or more [Parameter () ] 
attributes. When not specified, this parameter is a member of all parameter sets. 


ValueFromPipeline = $tru 


Declares this parameter as one that directly accepts pipeline input. If the user pipes data into your script or function, PowerShell assigns this 
input to your parameter in your command’s process {} block. When not specified, this parameter does not accept pipeline input 
directly. 


ValueFromPipelineByPropertyName = $true 


Declares this parameter as one that accepts pipeline input ifa property of an incoming object matches its name. If this is true, PowerShell 
assigns the value of that property to your parameter in your command’s process {} block. When not specified, this parameter does 
not accept pipeline mput by property name. 


ValueFromRemainingArguments = $true 
Declares this parameter as one that accepts all remaining input that has not otherwise been assigned to positional or named parameters. 
Only one parameter can have this element. Ifno parameter declares support for this capability, PowerShell generates an error for arguments 
that cannot be assigned. 

Parameter validation attributes 


In addition to the [Parameter () ] attribute, PowerShell lets you apply other attributes that add behavior or validation constraints to your 
parameters (all validation attributes are optional): 


[Alias ("name") ] 


Defines an alternate name for this parameter. This is especially helpful for long parameter names that are descriptive but have a more 
common colloquial term. When not specified, the parameter can be referred to only by the name you originally declared. 


[AllowNull () ] 


Allows this parameter to receive $nu11 as its value. This is required only for mandatory parameters. When not specified, mandatory 
parameters cannot receive $nu11 as their value, although optional parameters can. 


[AllowEmptyString() ] 


Allows this string parameter to receive an empty string as its value. This is required only for mandatory parameters. When not specified, 
mandatory string parameters cannot receive an empty string as their value, although optional string parameters can. You can apply this to 
parameters that are not strings, but it has no impact. 


[AllowEmptyCollection() ] 


Allows this collection parameter to receive an empty collection as its value. This is required only for mandatory parameters. When not 
specified, mandatory collection parameters cannot receive an empty collection as their value, although optional collection parameters can. 
You can apply this to parameters that are not collections, but it has no impact. 


[ValidateCount (lower limit,upper limit) ] 


Restricts the number of elements that can be in a collection supplied to this parameter. When not specified, mandatory parameters have a 
lower limit of one element. Optional parameters have no restrictions. You can apply this to parameters that are not collections, but it has no 
impact. 


[ValidateLength(lower limit,upper limit) ] 


Restricts the length of strings that this parameter can accept. When not specified, mandatory parameters have a lower limit of one character. 
Optional parameters have no restrictions. You can apply this to parameters that are not strings, but it has no impact. 


[ValidatePattern("regular expression") ] 


Enforces a pattern that input to this string parameter must match. When not specified, string inputs have no pattern requirements. You can 
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apply this to parameters that are not strings, but it has no impact. 


[ValidateRange (lower limit,upper limit) ] 


Restricts the upper and lower limit of numerical arguments that this parameter can accept. When not specified, parameters have no range 
limit. You can apply this to parameters that are not numbers, but it has no impact. 


[ValidateScript( { script block } )] 


Ensures that input supplied to this parameter satisfies the condition that you supply in the script block. PowerShell assigns the proposed 
input to the $_ (or $ PSI tem) variable, and then invokes your script block. Ifthe script block returns $t rue (or anything that can be 
converted to $t rue, such as nonempty strings), PowerShell considers the validation to have been successful. 


[ValidateSet ("First Option", "Second Option", ..., “Last Option") ] 


Ensures that input supplied to this parameter is equal to one of the options in the set. PowerShell uses its standard meaning of equality during 
this comparison: the same rules used by the -eq operator. If your validation requires nonstandard rules (such as case-sensitive comparison 
of strings), you can instead write the validation in the body of the script or function. 


[ValidateNotNull () ] 


Ensures that input supplied to this parameter is not null. This is the default behavior of mandatory parameters, so this is useful only for 
optional parameters. When applied to string parameters, a $nu11 parameter value gets instead converted to an empty string. 


[ValidateNotNullOrEmpty () ] 


Ensures that input supplied to this parameter is not null or empty. This is the default behavior of mandatory parameters, so this is useful only 
for optional parameters. When applied to string parameters, the input must be a string with a length greater than one. When applied to 
collection parameters, the collection must have at least one element. When applied to other types of parameters, this attribute is equivalent 
to the [ValidateNotNul1 () ] attribute. 


Pipeline input 
To access the data bemg passed to your command via the pipeline, use the input enumerator that PowerShell places in the $input special 
variable: 


foreach (Selement in Sinput) 


{ 


"Input was: Selement" 


} 
The $input variable is a NET enumerator over the pipeline input. Enumerators support streaming scenarios very efficiently but do not let you 


access arbitrary elements as you would with an array. Ifyou want to process their elements again, you must call the Reset () method on the 
$input enumerator once you reach the end. 


If you need to access the pipeline input in an unstructured way, use the following command to convert the input enumerator to an array: 
SinputArray = @(Sinput) 


Cmdlet keywords in commands 
When pipeline input is a core scenario of your command, you can include statement blocks labeled begin, process, and end: 


param(...) 


begin 


process 


end 


PowerShell executes the beg in statement when it loads your command, the process statement for each item passed down the pipeline, 
and the end statement after all pipeline input has been processed. In the process statement block, the $_ (or $ PSI tem) variable 
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represents the current pipeline object. 


When you write a command that includes these keywords, all the commands in your script must be contained within the statement blocks. 


$MylInvocation automatic variable 


The $MyInvocation automatic variable contains information about the context under which the script was run, including detailed 
information about the command (My Command), the script that defines it (ScriptName), and more. 


Retrieving Output from Commands 
PowerShell provides three primary ways to retrieve output froma command. 


Pipeline output 
any command 
The return value/output ofa script is any data that it generates but does not capture. Ifa command contains: 


"Text Output" 
5*5 


then assigning the output of that command to a variable creates an array with the two values Text Output and 25. 
Return statement 
return value 
The statement: 
return Sfalse 
is simply a short form for pipeline output: 


Sfalse 
return 


Exit statement 
exit errorlevel 


The exit statement returns an error code from the current command or instance of PowerShell. If called anywhere in a script (inline, in a 
function, or in a script block), it exits the script. If called outside ofa script (for example, a function), it exits PowerShell. The exit statement 
sets the $LastExitCode automatic variable to errorLevel. In turn, that sets the $? automatic variable to Sfalse if 
errorLevel is not zero. 


NOTE 


Type Get-Help about _automatic_variables for more information about automatic variables. 


Managing Errors 


PowerShell supports two classes of errors: nonterminating and terminating. It collects both types of errors as a list in the Ser ror automatic 
variable. 


Nonterminating Errors 


Most errors are nonterminating errors, in that they do not halt execution of the current cmdlet, script, function, or pipeline. When a command 
outputs an error (via PowerShell’s error-output facilities), PowerShell writes that error to a stream called the error output stream. 


You can output a nonterminating error using the Wr itte-Error cmdlet (or the WriteError () API when writing a cmdlet). 


The SErrorActionPreference automatic variable lets you control how PowerShell handles nontermmating errors. It supports the 
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following values, shown in Table 1-13. 


Table 1-13. ErrorActionPreference automatic variable values 


Value Meaning 
Ignore Do not display errors, and do not add themto the Serror collection. Only supported when supplied to the ErrorAction parameter ofa 
command. 


SilentlyContinu Do not display errors, but add themto the Serror collection. 
e 


Stop Treat nonterminating errors as terminating errors. 
Continue Display errors, but continue execution of the current cmdlet, script, function, or pipeline. This is the default. 
Inquire Display a prompt that asks how PowerShell should treat this error. 


Most cmdlets let you configure this explicitly by passing one of these values to the Er rorAction parameter. 


Terminating Errors 


A terminating error halts execution of the current cmdlet, script, function, or pipeline. Ifa command (such as a cmdlet or NET method call) 
generates a structured exception (for example, if you provide a method with parameters outside their valid range), PowerShell exposes this as a 
terminating error. PowerShell also generates a terminating error if it fails to parse an element of your script, function, or pipeline. 


You can generate a terminating error in your script using the throw keyword: 


throw message 


NOTE 


In your own scripts and cmdlets, generate terminating errors only when the fundamental intent of the operation is impossible to 
accomplish. For example, failing to execute a command on a remote server should be considered a nonterminating error, whereas failing 
to connect to the remote server altogether should be considered a terminating error. 


You can intercept terminating errors through the t ry, catch, and finally statements, as supported by many other programming 


languages: 


try 

statement block 

catch [exception type] 

error handling block 

catch [alternate exception type] 
alternate error handling block 
finally 


cleanup block 


After a t ry statement, you must provide a catch statement, a finally statement, or both. If you specify an exception type (which is 
optional), you may specify more than one catch statement to handle exceptions of different types. If you specify an exception type, the 
catch block applies only to terminating errors of that type. 


PowerShell also lets you intercept terminating errors if you define a t rap statement before PowerShell encounters that error: 


trap [exception type] 
{ 


statement block 
[continue or break] 


If you specify an exception type, the t rap statement applies only to terminating errors of that type. 
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Within a catch block or trap statement, the $__ (or $ PSI tem) variable represents the current exception or error being processed. 


If specified, the continue keyword tells PowerShell to continue processing your script, function, or pipeline after the point at which it 
encountered the termmating error. 


If specified, the break keyword tells PowerShell to halt processing the rest of your script, function, or pipeline after the point at which it 
encountered the terminating error. The default mode is break, and it applies if you specify neither break nor continue. 


Formatting Output 


Pipeline | Formatting Command 


When objects reach the end of the output pipeline, PowerShell converts them to text to make them suitable for human consumption. PowerShell 
supports several options to help you control this formatting process, as listed in Table 1-14. 


Table 1-14. PowerShell formatting commands 


Formatting Result 


command 
Format- Formats the properties ofthe input objects as a table, including only the object properties you specify. Ifyou do not specify a property list, 
Table PowerShell picks a default set. 


In addition to supplying object properties, you may also provide advanced formatting statements: 


PS > Get-Process | 
Format-Table -Auto Name, ` 
@{Label="HexId"; 
Expression={ "{0:x}" -f $_.Id} 
Width=4 
Align="Right" 
} 


The advanced formatting statement is a hashtable with the keys Label and Expression (or any short formof them). The value of the expression 
key should be a script block that returns a result for the current object (represented by the $_ variable). 


For more information about the Format-Table cmdlet, type Get-Help Format-Table. 


Format-List Formats the properties of the input objects as a list, including only the object properties you specify. If you do not specify a property list, 
PowerShell picks a default set. 


The Format-List cmdlet supports advanced formatting statements as used by the Format-Table cmdlet. 


The Format-List cmdlet is the one you will use most often to get a detailed summary of an object’s properties. 


The command Format-List * returns all properties, but it does not include those that PowerShell hides by default. The command Format- 
List * -Force returns all properties. 


For more information about the Format-List cmdlet, type Get-Help Format-List. 


50 
Formatting Result 
command 


Format—Wide Formats the properties of the input objects in an extremely terse summary view. If you do not specify a property, PowerShell picks a default. 


In addition to supplying object properties, you can also provide advanced formatting statements: 


PS > Get-Process | 
Format-Wide -Auto ` 
@{ Expression={ "{0:x}" -f $_.Id} } 


The advanced formatting statement is a hashtable with the key Expression (or any short formofit). The value of the expression key should be a 
script block that returns a result for the current object (represented by the $_ variable). 


For more information about the Format-Wide cmdlet, type Get-Help Format-Wide. 


Custom Formatting Files 


All the formatting defaults in PowerShell (for example, when you do not specify a formatting command, or when you do not specify formatting 
properties) are driven by the * Format.Ps1Xmi files in the installation directory. 


To create your own formatting customizations, use these files as a source of examples, but do not modify them directly. Instead, create a new 
file and use the Update-FormatData cmdkt to load your customizations. The Update-FormatData cmdkt applies your changes 
to the current instance of PowerShell. If you wish to load them every time you launch PowerShell, call Update-FormatData in your 
profile script. The following command loads Format.custom.ps1xml ftom the same directory as your profile: 


SformatFile = Join-Path (Split-Path Sprofile) 
"Format .Custom.Ps1Xm1" 
Update-FormatData —-PrependPath $formatFile 


Capturing Output 
There are several ways to capture the output of commands in PowerShell, as listed in Table 1-15. 


Table 1-15. Capturing output in PowerShell 


Command Result 
Svariable = Command Stores the objects produced by the PowerShell command into Svariable. 


Svariable = Command | Stores the visual representation of the PowerShell command into Svariable. This is the PowerShell command after it’s been 
Out-String converted to human-readable output. 


Svariable = Stores the (string) output of the native command into Svariable. PowerShell stores this as a list of strings—one for each line of 
NativeCommand output fromthe native command. 


Command-OutVariable For most commands, stores the objects produced by the PowerShell command into $variable. The parameter 
variable -OutVariable can also be written 


JON 


Command > File Redirects the visual representation of the PowerShell (or standard output ofa native command) into File, overwriting File ifit 
exists. Errors are not captured by this redirection. 


Command >> File Redirects the visual representation of the PowerShell (or standard output ofa native command) into File, appending to File ifit 
exists. Errors are not captured by this redirection. 


Command 2> File Redirects the errors fromthe PowerShell or native command into File, overwriting File if it exists. 


Command n>File Redirects streamnumber n into File, overwriting File if it exists. Supported streams are 2 for error, 3 for warning, 4 for verbose, 5 
for debug, 6 for the structured information stream, and * for all. 


Command 2>> File Redirects the errors fromthe PowerShell or native command into File, appending to File ifit exists. 


Command n>> File Redirects streamnumber n into File, appending to File ifit exists. Supported streams are 2 for error, 3 for warning, 4 for verbose, 
5 for debug, 6 for the structured information stream, and * for all. 
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Command Result 


Command > File2>&1 Redirects both the error and standard output streams of the PowerShell or native command into File, overwriting File if it exists. 


Command >> File2>&1 Redirects both the error and standard output streams of the PowerShell or native command into File, appending to File if it exists. 


While output from the Wr ite-Host cmdlet normally goes directly to the screen, you can use the structured information stream to capture it 
into a variable: 


PS > function HostWriter { Write-Host "Console Output" } 
PS > Sa = HostWriter 

Console Output 
PS > $a 

PS > Sa = HostWriter 6>&1 
PS > Sa 

Console Output 


Common Customization Points 


As useful as it is out of the box, PowerShell offers several avenues for customization and personalization. 


Console Settings 
The Windows PowerShell user interface offers several features to make your shell experience more efficient. 


Adjust your font size 
Both the Windows Terminal application and the default Windows Console let you adjust your font size. 


To temporarily change your font size, hold down the Ctrl key and use the mouse to scroll up or down. In the Windows Terminal application, 
you can also use the CtrH-Plus or CtrHMinus hotkeys. In the Windows Terminal application, Ctr-0 resets the font size back to your default. 


To change your font size default in the default Windows Console, open the System menu (right-click the title bar at the top left of the console 
window), select Properties—Font. Ifyou launch Windows PowerShell from the Start menu, it launches with some default modifications to the 
font and window size. To change your font size default in the Windows Terminal application, add a font Size setting to any of your terminal 
profiles: 


gurdi Woss y 

"name": "PowerShell (Demos)", 

"fontSize": 18, 

"colorScheme": "Campbell Powershell", 
"source": "Windows.Terminal.PowershellCore" 


}, 


Adjust other Windows Terminal settings 
The Windows Terminal application includes a wealth of configuration settings. A sample of these include: 
a Configuring the list of available shells and applications (such as bash. exe) 


= Color schemes and user interface themes 
= Binding actions to hotkeys 
a Text selection behavior 
= Window transparency 
= Background images 
For a full list of these, see the documentation for global settings and general profile settings in Windows Terminal. 


Use hotkeys to operate the shell more efficiently 
The PowerShell console supports many hotkeys that help make operating the console more efficient, as shown in Table 1-16. 


Table 1-16. PowerShell hotkeys 


Hotkey Meaning 


Hotkey 


Press and release the Windows key, and then 
type pwsh or powershell 


Up arrow 
Down arrow 
Left arrow 


Right arrow 


CtrHLeft arrow 
Ctr Right arrow 
Home 

End 


Ctr Shift+Pg Up, 
Ctr Shift+PgDn 


Ctrl Shift+F 


Alt+Space EK 
CtrH+-C 


CtrlH-V 


Ctr Shift+T 


CtrShift+W, Alt+F4 


Ctrl Break 


CtrHHome 


CtrHEnd 
CtrH-Z, Ctrl+Y 


F8 


CtrHR 
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Meaning 


Launch PowerShell or Windows PowerShell. The Win+X hotkey also provides a quick way to launch Windows 
PowerShell. 


Scan backward through your command history. 
Scan forward through your command history. 
Move cursor one character to the left on your command line. 


Move cursor one character to the right on your command line. If at the end of the line, inserts a character from 
the text of your last command at that position. 


Move the cursor one word to the left on your command line. 
Move the cursor one word to the right on your command line. 


Move the cursor to the beginning of the command line. 


Move the cursor to the end of the command line. 


In the Windows Terminal application, scroll through the screen buffer. In the Windows Console, you can use 
PgUp and PgDn. 


In the Windows Terminal application, searches for text in the screen buffer. In the Windows Console, you can 
use Alt+Space EF. 


In the Windows Console, selects text to be copied fromthe screen buffer. 
Cancel the current operation. If any text is selected, Ctrl+C copies this text into the clipboard. 
Paste clipboard contents. 


In the Windows Terminal application, opens a new tab. You can also use CtrHShift+1, CtrlShift+2, and similar 
to open a tab for that numbered profile (such as bash. exe). 


In the Windows Terminal application, close the current tab or entire application. In the Windows Console, you 
can use Altt+Space C to close the entire application. 


In the Windows Console, breaks the PowerShell debugger into the currently running script. 


Deletes characters fromthe beginning of the current command line up to (but not including) the current cursor 
position. 


Deletes characters from (and including) the current cursor position to the end of the current command line. 
Undo and Redo. 


Scan backward through your command history, only displaying matches for commands that match the text 
you’ve typed so far on the command line. 


Begins an interactive search backward through your command history based on text you type interactively. 


NOTE 


The command-line editing experience offered in PowerShell through the PSReadLine module is far richer than what this table lists. It 
includes Emacs and Vi key bindings, as well as the ability to define your own—you can see the full default list by typing Get- 


PSReadLineKeyHandler. 


Profiles 


PowerShell automatically runs the four scripts listed in Table 1-17 during startup. Each, if present, lets you customize your execution 
environment. PowerShell runs anything you place in these files as though you had entered it manually at the command line. 


Profile purpose 


Table 1-17. PowerShell profiles 


Profile location 


Customization of all PowerShell sessions, including PowerShell hosting applications for all users on JnstallationDirectory\profile.ps1 


the system 


Customization of pwsh.exe sessions for all users on the system 


Customization of all PowerShell sessions, including PowerShell hosting applications 


InstallationDirectory\Microsoft.PowerShell_profile.ps1 


<My Documents>\PowerShell\profile.ps1 
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Profile purpose Profile location 


Typical customization of pwsh.exe sessions <My 


Documents>\PowerShell\ Microsoft.PowerShell_profile.ps 
il 


In Windows PowerShell, some of these locations will be different. 


PowerShell makes editing your profile script simple by defining the automatic variable $pro file. By itself it points to the “current user, 
pwsh.exe”’ profile. In addition, the $p ro file variable defines additional properties that point to the other profile locations: 


PS > Sprofile | Format-List -Force 


AllUsersAllHosts : C:\...Microsoft.PowerShell..\profile.ps1 
AllUsersCurrentHost : C:\...\Microsoft.PowerShell profile.psl 
CurrentUserAllHosts D: \Lee\PowerShell\profile.ps1l 

CurrentUserCurrentHost : D:\...\Microsoft.PowerShell profile.ps1l 


To create a new profile, type: 


New-Item -Type file -Force Sprofile 


To edit this profile, type: 


notepad Sprofile 


Prompts 
To customize your prompt, add a prompt function to your profile. This function returns a string. For example: 


function prompt 


{ 
"PS [Senv:COMPUTERNAME] >" 


} 


Tab Completion 


You can define a TabExpansion2 function to customize the way that PowerShell completes properties, variables, parameters, and files 
when you press the Tab key. 

Your TabExpansion function overrides the one that PowerShell defines by default, though, so you may want to use its definition as a 
starting point: 


Get-Content function: \TabExpansion2 


User Input 


You can define a PSConsoleHostReadLine function to customize the way that the PowerShell console host (not the Integrated 
Scripting Environment [ISE]) reads input from the user. This function is responsible for handling all of the user’s keypresses, and finally returning 
the command that PowerShell should invoke. 


Command Resolution 


You can intercept PowerShell’s command resolution behavior in three places by assigning a script block to one or all of the 
PreCommandLookupAction, PostCommandLookupAction, or CommandNotFoundAction properties of 
SexecutionContext.SessionState.InvokeCommand. 


PowerShell invokes the PreCommandLookupAction after the user types a command name, but before it has tried to resolve the 
command. It invokes the Post CommandLookupAction once tt has resolved a command, but before it executes the command. It 
invokes the CommandNot FoundAction when a command is not found, but before it generates an error message. Each script block 
receives two arguments—C ommandName and CommandLookupEventArgs 


SexecutionContext.SessionState. 
InvokeCommand.CommandNotFoundAction = { 
param (SCommandName, 
SCommandLookupEventArgs) 


(esad 
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If your script block assigns a script block to the CommandScriptBlock property of the CommandLookupEventArgs or assigns a 


CommandIn fo to the Command property of the CommandLookupEventArgs, PowerShell will use that script block or command, 
respectively. If your script block sets the St opSearch property to t rue, PowerShell will do no further command resolution. 


Chapter 2. Regular Expression Reference 


Regular expressions play an important role in most text parsing and text matching tasks. They form an important underpinning of the -split 
and -match operators, the switch statement, the Select-String cmdlet, and more. Tables 2-1 through 2-10 list commonly used 


regular expressions. 


Table 2-1. Character classes: patterns that represent sets of characters 
Character class Matches 


Any character except for a newline. If the regular expression uses the SingleLine option, it matches any character. 


PS > "I" -matoh t4! 
True 


[characters] Any character in the brackets. For example: [aeiou]. 


leisy = Test? matoeh Hres]? 
True 


[^characters] Any character not in the brackets. For example: [^aeiou]. 


PS > "Test" -match '[*Tes]' 
False 


[| start-end] Any character between the characters start and end, inclusive. You may include multiple character ranges between the brackets. For 
example, [a-eh-j]. 


P3 > “Test match sale tl. 
True 


[^start-end] Any character not between any ofthe character ranges start through ena, inclusive. You may include multiple character ranges between 
the brackets. For example, [^a-eh-j]. 


PS > "Test" -match '[*e-t]' 
False 


\p{character Any character in the Unicode group or block range specified by {character class}. 
class} 


PS > "4" =meteh “\oism)}” 
True 
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Character class Matches 


\P{ character Any character not in the Unicode group or block range specified by {character class}. 


class} 
PS > "+" -match '\P{Sm}' 
False 

\w Any word character. Note that this is the Unicode definition ofa word character, which includes digits, as well as many math symbols and 

various other symbols. 

BS > "a" nagen AY 
True 

\w Any nonword character. 
PS > "I" -match '\W' 
True 

\s Any whitespace character. 
PSie u ti vematch a \ss 
True 

\s Any nonwhitespace character. 
PS >" >t -match '\S' 
False 

\d Any decimal digit. 
Po ASU maren a" 
True 

\D Any character that isn’t a decimal digit. 
PS > "!" -match '\D' 
True 


Table 2-2. Quantifiers: expressions that enforce quantity on the 
preceding expression 


Quantifier Meaning 
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Quantifier Meaning 


<none> One match. 


PS > "T" -matoh 'T! 
True 


* Zero or more matches, matching as much as possible. 


PS > SAU mate Chea TT 

True 

Poe Ee match OA 
TUS 


PS > 'ATTT' match 'AT*'; SMatches[0] 
True 
ATTT 


+ One or more matches, matching as much as possible. 


PS > "A" -match 'T+! 

False 

PS > "TTTTT" -match '*T+S' 
True 


PS > 'ATTT' -match 'AT+'; S$Matches[0] 


True 
ATTT 


? Zero or one matches, matching as much as possible. 


is) SS Wa ee Vung 
False 


PS > "ATIT" -match VAL? “SMatehes [0] 
True 
AT 


{n} Exactly n matches. 


PS > "TTTTT" -match '*T{5}$' 
True 


{n,} nor more matches, matching as much as possible. 


PSEA OTTEET maten Teele om 
True 


58 
Quantifier Meaning 


{n,m} Between nand mmatches (inclusive), matching as much as possible. 


PS > "TTTTT" -match '*T{4,6}$' 
True 


#2 Zero or more matches, matching as little as possible. 


P3 = YA" -match UoAT aes! 
True 


PS > 'ATTT' -match 'AT*?'; $Matches[0] 


True 
A 


+? One or more matches, matching as little as possible. 


PS > "A" -match '*AT+?$!' 
False 


PS > 'ATTT' -match 'AT+?'; SMatches [0] 


True 
AT 


2? Zero or one matches, matching as little as possible. 


PS > “AN =match "AT? ?S 
True 


PS > 'ATTT' -match 'AT??'; $Matches[0] 
True 
A 


{n}? Exactly n matches. 


PS > "TTTTT" -match '*T{5}?$' 
True 


{ery ie, nor more matches, matching as little as possible. 


BS > VTITER —match, “ATi 4e} 2s" 
True 


{n,m}? Between nand mmatches (inclusive), matching as little as possible. 


PS > "TTTTT" -match '*T{4,6}?S$' 
True 
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Table 2-3. Grouping constructs: expressions that let you group characters, patterns, and other expressions 


Grouping Description 

construct 

(text) Captures the text matched inside the parentheses. These captures are named by number (starting at one) based on the order of the opening 
parenthesis. 


PS > "Hello" -match '%(.*)1lloS'; 
Smatches [1] 

True 

He 


(?<name>) Captures the text matched inside the parentheses. These captures are named by the name given in name. 


PS > "Hello" -match '*(?<One>.*)1lloS'; 
Smatches.One 

True 

He 


(?<namel-name2>) A balancing group definition. This is an advanced regular expression construct, but lets you match evenly balanced pairs of terms. 


a) Noncapturing group. 


PS > "Al" -match '((A|B)\d)'; $matches 


True 

Name Value 
2 A 

il Al 

0 Al 


PS > "Al" -match '((?:A|B)\d)'; Smatches 


True 

Name Value 
il Al 

0 Al 


(?imnsx-imnsx:) Applies or disables the given option for this group. Supported options are: 


aE case-insensitive 
m multiline 
n explicit capture 
s singleline 
x ignore whitespace 


PS > "Te*’nst" -match '(T e.st)' 
False 

PS > "Te`nst" -match '(?sx:T e.st)' 
True 
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Grouping Description 
construct 
(2=) Zero-width positive lookahead assertion. Ensures that the given pattern matches to the right, without actually performing the match. 
po Se Sgan 2125 ematen Y (=o 55S) (oe) te 
$matches [1] 
True 
25571212 
(2?!) Zero-width negative lookahead assertion. Fnsures that the given pattern does not match to the right, without actually performing the 
match. 


PS > "friendly" -match '(?!friendly)friend' 


False 
Table 2-4. More grouping constructs 
Grouping Description 
construct 
(?<=) Zero-width positive lookbehind assertion. Fnsures that the given pattern matches to the left, without actually performing the match. 
PS > "public int X" -match '%.*(?<=public Jint +$? 
True 
(2<!) Zero-width negative lookbehind assertion. Ensures that the given pattern does not match to the left, without actually performing the 
match. 
PS > "private int X" -match =^. *(2<lprivate Jint 4S 
False 
(?>) Nonbacktracking subexpression. Matches only if this subexpression can be matched completely. 


PS > "Hello World" -match '(Hello.*)orld' 
True 

PS > "Hello World" -match '(?>Hello.*)orld' 
False 


The nonbacktracking version of the subexpression fails to match, as its complete match would be “Hello World”. 


Table 2-5. Atomic zero-width assertions: patterns that restrict where a match may occur 


Assertion Restriction 
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Assertion Restriction 


A The match nust occur at the beginning ofthe string (or line, ifthe Multiline option is in effect). 


PS > "Test" -match "est! 
False 


$ The match must occur at the end of the string (or line, ifthe Multiline option is in effect). 


PS > "Test" -match 'Tes$' 
False 


\A The match must occur at the beginning of the string. 


PS > "The*nTest" -match '(?m:*Test)' 


True 
PS > "The*nTest" -match '(?m:\ATest) ' 
False 
Nz The match must occur at the end of the string, or before \n at the end of the string. 


PS > "The *nTest*n" -match '(?m:The$) ' 


True 
PS > "The*nTest*n" -match '(?m:The\Z) ' 
False 
PS > "The*nTest*n" -match 'Test\Z' 
True 

\z The match must occur at the end of the string. 


PS > "The`nTest`n" -match 'Test\z' 
False 


\G The match must occur where the previous match ended. Used with 


System. Text .RegularExpressions.Match.NextMatch () 


\b The match must occur on a word boundary: the first or last characters in words separated by nonalphanumeric characters. 


PS > "Testing" -match 'ing\b' 
True 
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Assertion Restriction 


\B The match nust not occur on a word boundary. 


PS > “Testing” match ‘ing\B’ 
False 


Table 2-6. Substitution patterns: patterns used in a regular 
expression replace operation 


Pattern Substitution 


$number The text matched by group number number. 


PS > "Test" -replace "(.*)st",'Slar' 
Tear 


${name} The text matched by group named name. 


PS > "Test" -replace "(?<pre>.*)st",'S{pre}ar' 


Tear 

$$ A literal $. 
PS > "Test" -replace ".",'$$' 
$$$$ 

$& A copy ofthe entire match. 


PS > "Test" =replace "“.*S",'Found: $5" 
Found: Test 


$` The text of the input string that precedes the match. 


PS > "Test" -replace "est$",'TeS$*' 
TTeT 


ou The text of the input string that follows the match. 


PS > "Test" -replace "*Tes",'Res$''!' 
Restt 
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Pattern Substitution 


$+ The last group captured. 
PS > "Testing" -replace "(.*)ing",'$+ed' 
Tested 

Si The entire input string. 
Poe Testings replace ingu String: oii 


String: Testing 


Table 2-7. Alternation constructs: expressions that let you perform either/or logic 


Alternation Description 
construct 


Matches any of the terms separated by the vertical bar character. 


PS > "Test" -match '(B|T)est' 


True 
(? (expression) Matches the yes term if expression matches at this point. Otherwise, matches the no term. The no term is optional. 
yes | no) 

Po "3.14" maton ENE 14a” 

TENE 

PS > SEN mateh ON S AEI 

True 

Po > M27 =maten “Pie 4)” 

False 
(? (name) yes| no) Matches the yes term if the capture group named name has a capture at this point. Otherwise, matches the no term. The no term is 

optional. 


PS > "123" -match ! (?<one>1) ?(? (one) 23|234)' 


True 
PS > "23" -match '(?<one>1) ?(? (one) 23/234) ' 
False 
PS > "234" -match ! (?<one>1) ?(? (one) 23|234)' 
True 


Table 2-8. Backreference constructs: expressions that refer to a capture group 
within the expression 


Backreference construct Refers to 


Escaped 
character 


<ordinary 


characters> 


\a 
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Backreference construct Refers to 


\number Group number number in the expression. 
PS > "|Text|" -match '(.)Text\1' 
True 
PS > "|Text+" -match '(.)Text\1' 
False 

\k<name> The group named name in the expression. 


PS > "|Text|" match ' (?<Symbol>.)Text\k<Symbol>' 
True 
PS > "|Text+" -match '(?<Symbol>.)Text\k<Symbol>' 
False 


Table 2-9. Other constructs: other expressions that modify a regular expression 


Construct Description 


(?imnsx-imnsx) Applies or disables the given option for the rest of this expression. Supported options are: 


i case-insensitive 
m multiline 
n explicit capture 
5 singleline 
x ignore whitespace 


PS > "Te`nst" -match '(?sx)T e.st' 
True 


(2# ) Inline comment. This terminates at the first closing parenthesis. 


PS > "Test" -match '(?# Match "Test")Test' 
True 


# [to end ofline] Comment formallowed when the regular expression has the IgnoreWhitespace option enabled. 


PS > "Test" -match '(?x)Test # Matches Test' 
True 


Table 2-10. Character escapes: character sequences that represent another character 


Match 


Characters other than. $ ^ { [ ( | ) * + ? \ match themselves. 


A bell (alarm) \u0007. 


‘Escaped 
character 


\b 


\e 


\ ddd 


\xdd 
\ee 
\udddd 


\ 
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Match 


A backspace \u0008 if in a [] character class. In a regular expression, \b denotes a word boundary (between \w and \w characters) except within 
a [] character class, where \b refers to the backspace character. In a replacement pattern, \b always denotes a backspace. 

A tab \u0009. 

A carriage return \u000D. 

A vertical tab \u000B. 

A form feed \u000c. 

A new line \u000A. 

An escape \u001B. 


An ASCII character as octal (up to three digits). Numbers with no leading zero are treated as backreferences if they have only one digit, or if they 
correspond to a capturing group number. 


An ASCII character using hexadecimal representation (exactly two digits). 
An ASCII control character; for example, \cc is Control-C. 
A Unicode character using hexadecimal representation (exactly four digits). 


When followed by a character that is not recognized as an escaped character, matches that character. For example, \* is the literal character *. 


Chapter 3. XPath Quick Reference 


Just as regular expressions are the standard way to interact with plain text, XPath is the standard way to interact with XML. Because of that, 
XPath is something you’re likely to run across in your travels. Several cmdlets support XPath queries: Se lect -Xm1l, Get-WinEvent, 
and more. Tables 3-1 and 3-2 give a quick overview of XPath concepts. 


For these examples, consider this sample XML: 


<AddressBook> 
<Person contactType="Personal"> 
<Name>Lee</Name> 
<Phone type="home">555-1212</Phone> 
<Phone type="work">555-1213</Phone> 
</Person> 
<Person contactType="Business"> 
<Name>Ariel</Name> 
<Phone>555-1234</Phone> 
</Person> 
</AddressBook> 


Table 3-1. Navigation and selection 


Syntax Meaning 
/ Represents the root of the XML tree. 
For example: 


PS > $xml | Select-Xml "/" | 
Select -Expand Node 


AddressBook 


AddressBook 


/Node Navigates to the node named Node fromthe root of the XML tree. 


For example: 


PS > $xml | Select-Xml "/AddressBook" | 
Select -Expand Node 


Person 


{Lee, Ariel} 


/Node/*/Node2 Navigates to the node named Node2 via Node, allowing any single node in between. 


For example: 


PS > $xml | Select-Xml "/AddressBook/*/Name" | 
Select -Expand Node 
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Syntax Meaning 
//Node Finds all nodes named Node, anywhere in the XML tree. 
For example: 


PS > $xml | Select-Xml "//Phone" | 
Select -Expand Node 


type #text 

home 555-1212 

work 55521213 
55571234 


3 Retrieves the parent node of the given node. 


For example: 


PS > $xml | Select-Xml "//Phone" | 
Select -Expand Node 


type #text 

home p5o9=1212 

work 5551213 
555-1234 


PS > $xml | Select-Xml "//Phone/.."| 
Select -Expand Node 


contactType Name Phone 
Personal Lee {Phone, Phone} 
Business Ariel 555-1234 


@ Attribute Accesses the value ofthe attribute named Attribute. 


For example: 


PS > $xml | Select-Xml "//Phone/@type" | 
Select -Expand Node 


Table 3-2. Comparisons 


Syntax Meaning 
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Syntax Meaning 


| 


and 


or 


not () 


Filtering, similar to the Where-Object cmdlet. 


For example: 


PS > $xml | 
Select-Xml "//Person[@contactType = 'Personal']" | 
Select -Expand Node 


contactType Name Phone 
Personal Lee {Phone, Phone} 
PS > $xml | Select-Xml "//Person[Name = 'Lee']" | 


Select -Expand Node 


contactType Name Phone 


Personal Lee {Phone, Phone} 


Logical and. 


Logical or. 


Logical negation. 


Equality. 


Inequality. 


Chapter 4. .NET String Formatting 


String Formatting Syntax 
The format string supported by the format (- £) operator is a string that contains format items. Each format item takes the form of: 


{ index[, alignment] [: formatString] } 


index represents the zero-based index of the item in the object array following the format operator. 


alignment is optional and represents the alignment of the item. A positive number aligns the item to the right ofa field of the specified width. 
A negative number aligns the item to the left ofa field of the specified width: 


PS > ("{0,6}" -f 4.99), ("{0,6:##.00}" -f 15.9) 
4.99 
15.90 


formatString is optional and formats the item using that type’s specific format string syntax (as laid out in Tables 4-1 and 4-2). 


Standard Numeric Format Strings 


Table 4-1 lists the standard numeric format strings. All format specifiers may be followed by a number between 0 and 99 to control the 
precision of the formatting, 


Table 4-1. Standard numeric format strings 


Format Name Description 


specifier 
Core Curren A currency amount: 
cy 
BS > "LOTCH" =f 1.23 
$1.23 
Dord Decima A decimal amount (for integral types). The precision specifier controls the minimum number of digits in the result: 
1 
PS > "{0:D4}" -£ 2 
0002 
Eore Scientif Scientific (exponential) notation. The precision specifier controls the number of digits past the decimal point: 
ic 
PS > "{O0:E3}" =£ [Math]::Pi 
3.142E+000 
Forf Fixed- Fixed-point notation. The precision specifier controls the number of digits past the decimal point: 
point 


BS S VlOsins sie Meio aa eal 
3.142 
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Format Name Description 


specifier 
Gorg General The most compact representation (between fixed-point and scientific) of the number. The precision specifier controls the number of 
significant digits: 
PS > "{0:G3}" -£ [Math]::Pi 
3.14 
PS > "{0:G3}" =£ 1mb 
1.05E+06 
Norn 


Numbe The human-readable form of the number, which includes separators between number groups. The precision specifier controls the number of 
f digits past the decimal point: 


Poe RONA ET mG 
1,048,576.0000 


Porp Percent The number (generally between 0 and 1) represented as a percentage. The precision specifier controls the number of digits past the decimal 
point: 
PS > "{0:P4}" =f 0.67 
67.0000 % 
Rorr Roundt The Single or Double number formatted with a precision that guarantees the string (when parsed) will result in the original number again: 
rip 
PS Os Rie Emo) 
524288 
PST ORRIA E Imb iOr0)) 
116508.44444444444 
X Or x 


Hexade The number converted to a string of hexadecimal digits. The case of the specifier controls the case of the resulting hexadecimal digits. The 
cimal precision specifier controls the minimum number of digits in the resulting string: 


PS > "{0:X4}" -f 1324 
052C 


Custom Numeric Format Strings 
You can use custom numeric strings, listed in Table 4-2, to format numbers in ways not supported by the standard format strings. 


Table 4-2. Custom numeric format strings 


Format Name Description 
specifier 
0 Zero 


Specifies the precision and width ofa number string. Zeros not matched by digits in the original number are output as zeros: 
placeholder 


PS > "{0:00.0}" -£ 4.12341234 
04.1 


Format Name 

specifier 

# Digit 
placeholder 
Decimal point 

7 Thousands 
separator 
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Description 


Specifies the precision and width ofa number string. # symbols not matched by digits in the input number are not output: 


PS > "(O:##.#}" E 4.12341234 
4.1 


Determines the location of the decimal: 


PS > "{O:##.#}" -f 4.12341234 
4.1 


When placed between a zero or digit placeholder before the decimal point in a formatting string, adds the separator character 
between number groups: 


PS > "{0:#,#.#}" -f 1234.121234 
1,234.1 


; Number scaling When placed before the literal (or implicit) decimal point in a formatting string, divides the input by 1,000. You can apply this 


% Percentage 
placeholder 

EO Scientific 
notation 

E+0 

E-0 

e0 

e+0 


format specifier more than once: 


PS > "{O:##,,.000}" -f 1048576 
1.049 


Multiplies the input by 100, and inserts the percent sign where shown in the format specifier: 


PS > “OrsHt. O00)" —£ .68 
368.000 


Displays the input in scientific notation. The number of zeros that follow the Edefine the minimum length of the exponent field: 


PS > "{O:##.#EO000}" -f 2.71828 
27.2E-001 
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Format Name Description 
specifier 


Certi Literal string Inserts the provided text literally into the output without affecting formatting: 


Wigex tu 
PS > "{O:#.00'##"'}" -E 2.71828 
2.7244 


7 Section Allows for conditional formatting. 
separator 


If your format specifier contains no section separators, the formatting statement applies to all input. 


If your format specifier contains one separator (creating two sections), the first section applies to positive numbers and zero, and 
the second section applies to negative numbers. 


If your format specifier contains two separators (creating three sections), the sections apply to positive numbers, negative 
numbers, and zero: 


PS > "{0:POS;NEG; ZERO}" -f -14 
NEG 


Other Other character Inserts the provided text literally into the output without affecting formatting: 


PS > "{O:S## Please}" -f 14 
$14 Please 


Chapter 5. .NET DateTime Formatting 


DateTime format strings convert a DateTime object to one of several standard formats, as listed in Table 5-1. 


Table 5-1. Standard DateTime format strings 


Format specifier Name Description 


d Short date The culture’s short date format: 


PS > "{0:d}" -f [DateTime] "01/23/4567" 
1/23/4567 


D Long date The culture’s long date format: 


PS > "{0:D}" -f£ [DateTime] "01/23/4567" 
Friday, January 23, 4567 


E Full date/short time Combines the long date and short time format patterns: 


PS > "{0:f}" -f [DateTime] "01/23/4567" 
Friday, January 23, 4567 12:00 AM 


F Full date/long time Combines the long date and long time format patterns: 


PS > "{O0:F}" -f [DateTime] "01/23/4567" 
Friday, January 23, 4567 12:00:00 AM 


g General date/ short time Combines the short date and short time format patterns: 


PS > "{O:g}" -f [DateTime] "01/23/4567" 
1/23/4567 12:00 AM 


G General date/long time Combines the short date and long time format patterns: 


PS > "{0:e)" =f [DateTime] "01/23/4567" 
1/23/4567 12:00:00 AM 


Morm Month day The culture’s MonthDay format: 


PS > "{0:M}" -f [DateTime] "01/23/4567" 
January 23 
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Format specifier Name Description 


o Round-trip date/time The date formatted with a pattern that guarantees the string (when parsed) will result in the original DateTime again: 


PS > "{0:0}" e [DateTime] "01/23/4567" 
4567-01-23T00:00:00.0000000 


Rorr RFC1123 The standard RFC1123 format pattern: 


PS > "{0:R}" -f [DateTime] "01/23/4567" 
Fri, 23 Jan 4567 00:00:00 GMT 


s Sortable Sortable format pattern. Conforms to ISO 8601 and provides output suitable for sorting: 


PS > "{0:s}" -£ [DateTime] "01/23/4567" 
4567-01-23T00:00:00 


t Short time The culture’s Short Time format: 


PS > "{O:t}" -f [DateTime] "01/23/4567" 
12:00 AM 


i Long time The culture’s LongTime format: 


PS > "{07:T}" =f [DateTime] "01/23/4567" 
12:00:00 AM 


u Universal sortable The culture’s UniversalSortable DateTime format applied to the UTC equivalent of the input: 
PS > "{O:u}" -f [DateTime] "01/23/4567" 
4567-01-23 00:00:002 


U Universal The culture’s Full DateTime format applied to the UTC equivalent of the input: 


PS > "{0:U}" -f [DateTime] "01/23/4567" 
Friday, January 23, 4567 8:00:00 AM 


Yory Year month The culture’s YearMonth format: 


PS > "{0:Y}" -f [DateTime] "01/23/4567" 
January, 4567 
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Custom DateTime Format Strings 


You can use the custom DateTime format strings listed in Table 5-2 to format dates in ways not supported by the standard format strings. 


NOTE 


Single-character format specifiers are by default interpreted as a standard DateTime formatting string unless they are used with other 
formatting specifiers. Add the % character before them to have them interpreted as a custom format specifier. 


Table 5-2. Custom DateTime format strings 


Format Description 
specifier 
d Day ofthe month as a number between 1 and 31. Represents single-digit days without a leading zero: 


PS > "{O:%d}" -f£ 
[DateTime] "01/02/4567" 
2 


dd Day of the month as a number between | and 31. Represents single-digit days with a leading zero: 


PS > "{O:dd}" -£ 
[DateTime] "01/02/4567" 
02 


ddd Abbreviated name of the day of week: 


PS > "(Orddd}" =f 
[DateTime] "01/02/4567" 
Fri 


dddd Full name of the day of the week: 


its) es WiOarelelelel yy Sie 
[DateTime] "01/02/4567" 
Friday 


f Most significant digit of the seconds fraction (milliseconds): 


PS > $date = Get-Date 
PS > $date.Millisecond 
93 
PS > "{0:%f}" -f $date 
0 
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Format Description 
specifier 
fE Two most significant digits ofthe seconds fraction (milliseconds): 


PS > $date = Get-Date 
PS > $date.Millisecond 


93 
PS > MOLTE f Sdate 
09 
fff Three most significant digits ofthe seconds fraction (milliseconds): 


PS > $date = Get-Date 
PS > $date.Millisecond 


93 
PS > "{0:fff}" -f $date 
093 
EERE Four most significant digits ofthe seconds fraction (milliseconds): 


PS > $date = Get-Date 
PS > $date.Millisecond 


93 
BSS MORTEN -f Sdate 
0937 
fffft Five most significant digits of the seconds fraction (milliseconds): 


PS > $date = Get-Date 
PS > $date.Millisecond 


93 
PS > "{O:fffff}" -f $date 
09375 
fEELLE Six most significant digits of the seconds fraction (milliseconds): 


PS > $date = Get-Date 
PS > $date.Millisecond 


93 
PS VOLENU E Sdaite 
093750 
£ELFELL Seven most significant digits of the seconds fraction (milliseconds): 


PS > $date = Get-Date 

PS > $date.Millisecond 

93 

PS > "{O:fffffff}" =£ Sdate 
0937500 
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Format Description 

specifier 

F Most significant digit of the seconds fraction (milliseconds). 

FF When compared to the lowercase series of 'f' specifiers, displays nothing ifthe number is zero: 
FFF 


PS > "{Oo|F ER BER PERE |} —£ 
[DateTime] "01/02/4567" 
| [=== 


FFFFFFF 
%g or gg Fra (e.g., A.D.): 
PS > "{0:gg}" -f [DateTime] 
"01/02/4567" 
A.D. 
sh Hours, as a number between 1 and 12. Single digits do not include a leading zero: 
PS o TO SDAS 
[DateTime] "01/02/4567 4:00pm" 
4 
hh Hours, as a number between 01 and 12. Single digits include a leading zero. Note: this is interpreted as a standard DateTime formatting string 
unless used with other formatting specifiers: 
PS > "{O:hh}" =f 
[DateTime] "01/02/4567 4:00pm" 
04 
SH Hours, as a number between 0 and 23. Single digits do not include a leading zero: 
PoS UNOS aR ae 
[DateTime] "01/02/4567 4:00pm" 
16 
HH Hours, as a number between 00 and 23. Single digits include a leading zero: 


PS > "{O:HH}" -f 
[DateTime] "01/02/4567 4:00am" 
04 


Format 
specifier 
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Description 


DateTime .Kind specifier that corresponds to the kind (i.e., local, UTC, or unspecified) of input date: 


PoS TOSE k ae 
[DateTime] : :Now.ToUniversalTime () 
Z 


Minute, as a number between 0 and 59. Single digits do not include a leading zero: 


PS > "{0:%m}" -f [DateTime] ::Now 
T 


Minute, as a number between 00 and 59. Single digits include a leading zero: 


PS > "{0:mm}" -f [DateTime] ::Now 
08 


Month, as a number between 1 and 12. Single digits do not include a leading zero: 


PS > "{O:3M}" =f 
[DateTime] "01/02/4567" 
1 


Month, as a number between 01 and 12. Single digits include a leading zero: 


RS S OSIM ar 
[DateTime] "01/02/4567" 
01 


Abbreviated month name: 


PS > "{0:MM}" -f 
[DateTime] "01/02/4567" 
Jan 


Full month name: 


PS > "{0:MMMM}" =f 
[DateTime] "01/02/4567" 
January 
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Format Description 
specifier 
s Seconds, as a number between 0 and 59. Single digits do not include a leading zero: 


PS > $date = Get-Date 
PS > "{0:%s}" -f $date 
7 


ss Seconds, as a number between 00 and 59. Single digits include a leading zero: 


PS > $date = Get-Date 
PS > "{0tssi” =f Sdate 
07 


t First character of the a.m/p.m. designator: 


PS > $date = Get-Date 
PS > "{0:%t}" -f $date 
P 


tt a.m/p.m. designator: 


PS > $date = Get-Date 
PS MOE) rf sdate 
PM 


y Year, in (at most) two digits: 


PS > "{O:%Sy}" -=£ 
[DateTime] "01/02/4567" 
67 


yy Year, in (at most) two digits: 


es} SS YANO RNAV ie 
[DateTime] "01/02/4567" 
67 


yyy Year, in (at most) four digits: 


PS > "{O:yyy}" +f 
[DateTime] "01/02/4567" 
4567 
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Format Description 
specifier 
yyyy Year, in (at most) four digits: 


PS > "{O:yyyy}" E 
[DateTime] "01/02/4567" 
4567 


yyyyy Year, in (at most) five digits: 


PS > "{0:yyyy}" -f 
[DateTime] "01/02/4567" 
04567 


z Signed time zone offset from GMT. Does not include a leading zero: 


PS > "{0:%z}" -f [DateTime] ::Now 
=8 


ZZ Signed time zone offset from GMT. Includes a leading zero: 


PS > "{O:zz}" -f [DateTime] ::Now 
-08 


ZZZ Signed time zone offset from GMT, measured in hours and minutes: 


PS > "{0:zzz}" -f [DateTime] ::Now 
=08:00 


Time separator: 


PS > "{O:y/m/d h:m:s}" =f 
[DateTime] "01/02/4567 4:00pm" 
67/0/2 4:0:0 


/ Date separator: 


BS e HTO Ae neme E 
[DateTime] "01/02/4567 4:00pm" 
67/0/2 4:0:0 


Format 
specifier 


" text" 


' text ' 


aie 
Q 


Other 
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Description 


Inserts the provided text literally into the output without affecting formatting: 


PS > "{O:'Day: 'dddd}" =E 
[DateTime] : :Now 
Day: Monday 


Syntax allowing for single-character custom formatting specifiers. The % sign is not added to the output: 


ies) B= WOR rela ae 
[DateTime] "01/02/4567 4:00pm" 
4 


Inserts the provided text literally into the output without affecting formatting: 


PS > "{O:dddd!}" -f [DateTime] ::Now 
Monday! 


Chapter 6. Se 


lected .NET Classes and Their Uses 


Tables 6-1 through 6-16 provide pointers to types in the .NET Framework that usefùlly complement the functionality that PowerShell provides. 
For detailed descriptions and documentation, refer to the official documentation. 


Class 


System.Management. 


Class 

System. DateTime 
System.Guid 
System.Math 


System. Random 


System.Convert 
System. Environment 
System.Console 


System. Text. Regular 
Expressions .Regex 


System.Diagnostics .Debug 
System.Diagnostics.EventLog 
System. Diagnostics. Process 
System. Diagnostics.Stopwatch 


System.Media.SoundPlayer 


Class 


System.Array 


System.Enum 
System.String 
System. Text.StringBuilder 


System.Collections. 
Specialized.OrderedDictionary 


System.Collections.ArrayList 


Table 6-1. PowerShell 


Description 


Automation.PSObject Represents a PowerShell object to which you can add notes, properties, and more. 


Table 6-2. Utility 


Description 

Represents an instant in time, typically expressed as a date and time of day. 

Represents a globally unique identifier (GUID). 

Provides constants and static methods for trigonometric, logarithmic, and other common mathematical functions. 


Represents a pseudorandom number generator, a device that produces a sequence of numbers that meet certain statistical 
requirements for randomness. 


Converts a base data type to another base data type. 
Provides information about, and means to manipulate, the current environment and platform. 
Represents the standard input, output, and error streams for console applications. 


Represents an immutable regular expression. 


Provides a set of methods and properties that help debug your code. 

Provides interaction with Windows event logs. 

Provides access to local and remote processes and enables you to start and stop local system processes. 
Provides a set of methods and properties that you can use to accurately measure elapsed time. 


Controls playback of a sound froma .wav file. 


Table 6-3. Collections and object utilities 


Description 


Provides methods for creating, manipulating, searching, and sorting arrays, thereby serving as the base class for 
all arrays in the Common Language Runtime. 


Provides the base class for enumerations. 
Represents text as a series of Unicode characters. 
Represents a mutable string of characters. 


Represents a collection of key/value pairs that are accessible by the key or index. 


Implements the [List interface using an array whose size is dynamically increased as required. 


Table 6-4. The .NET Framework 


Class Description 


System. AppDomain Represents an application domain, which is an isolated environment where applications execute. 


System.Reflection.As Defines an Assembly, which is a reusable, versionable, and self-describing building block of a Common Language Runtime 
sembly application. 


System. Type Represents type declarations: class types, interface types, array types, value types, enumeration types, type parameters, generic 
type definitions, and open or closed constructed generic types. 


Class 


System. Threading. Thr 


ead 


System.Runtime. 


Interop 
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Description 


Creates and controls a thread, sets its priority, and gets its status. 


Provides a collection of methods for allocating unmanaged memory, copying unmanaged memory blocks, and converting managed 


to unmanaged types, as well as other miscellaneous methods used when interacting with unmanaged code. 


Services.Marshal 


Microsoft.CSharp.CSh 


arpCodeProvider 


Class 


Provides access to instances of the C# code generator and code compiler. 


Table 6-5. Registry 


Description 


Microsoft.Win32.Registr Provides RegistryKey objects that represent the root keys in the local and remote Windows Registry and static methods to 
access key/value pairs. 


y 


Microsoft.Win32.Registr Represents a key-level node in the Windows Registry. 


yKey 


Class 

System. 
System. 
System. 
System. 
System. 


System. 


System. 


System. 


System. 


System. 


System. 
System. 
System. 
System. 
System. 
System. 


System. 
eStream 


System. 
ream 


System. 


Class 


O. 


oO. 


O. 


Stream 
.BinaryReader 
.BinaryWriter 
.BufferedStream 
Directory 


.FileInfo 


.DirectoryInfo 


.File 


.MemoryStream 


‘Path 


.TextReader 
. StreamReader 
.TextWriter 
.StreamWriter 
.StringReader 


.StringWriter 


Compression.Deflat 


Compression.GZipSt 


FileSystemWatcher 


System.Security.Principal. 
WindowsIdentity 


Table 6-6. Input and Output 


Description 

Provides a generic view ofa sequence of bytes. 

Reads primitive data types as binary values. 

Writes primitive types in binary to a stream. 

Adds a buffering layer to read and write operations on another stream. 

Exposes static methods for creating, moving, and enumerating through directories and subdirectories. 


Provides instance methods for creating, copying, deleting, moving, and opening files, and aids in the creation of 
FileStream objects. 


Exposes instance methods for creating, moving, and enumerating through directories and subdirectories. 


Provides static methods for creating, copying, deleting, moving, and opening files, and aids in the creation of 
FileStream objects. 


Creates a stream whose backing store is memory. 


Performs operations on String instances that contain file or directory path information. These operations are performed 
in a cross-platform manner. 


Represents a reader that can read a sequential series of characters. 

Implements a TextReader that reads characters froma byte stream in a particular encoding. 
Represents a writer that can write a sequential series of characters. 

Implements a TextWriter for writing characters to a streamin a particular encoding. 
Implements a TextReader that reads froma string. 

Implements a Text Writer for writing information to a string. 


Provides methods and properties used to compress and decompress streams using the Deflate algorithm. 


Provides methods and properties used to compress and decompress streams using the GZip algorithm. 


Listens to the filesystem change notifications and raises events when a directory or file in a directory changes. 


Table 6-7. Security 


Description 


Represents a Windows user. 


84 


Class Description 

System.Security.Principal. Allows code to check the Windows group membership of a Windows user. 

WindowsPrincipal 

System.Security.Principal. Defines a set of commonly used security identifiers (SIDs). 

WellKnownSidType 

System.Security.Principal. Specifies common roles to be used with IsInRole. 

WindowsBuiltInRole 

System. Security.SecureString Represents text that should be kept confidential. The text is encrypted for privacy when being used and 


deleted from computer memory when no longer needed. 


System.Security.Cryptography. Defines a wrapper object to access the cryptographic service provider (CSP) version of the TripleDES 
TripleDESCryptoServiceProvider algorithm. 
System. Security.Cryptography. Derives a key froma password using an extension of the PBKDF1 algorithm. 


PasswordDeriveBytes 
System.Security.Cryptography.SHA1 Computes the SHA1 hash for the input data. 


System.Security.Access Represents the access control and audit security for a file or directory. 
Control.FileSystemSecurity 


System.Security.Access Represents the Windows access control security for a registry key. 
Control.RegistrySecurity 


Table 6-8. User interface 


Class Description 
System.Windows . Forms . Form Represents a window or dialog box that makes up an application’s user interface. 


System.Windows.Forms.FlowLayoutPanel Represents a panel that dynamically lays out its contents. 


Table 6-9. Image manipulation 


Class Description 


System.Drawing.I A class that provides functionality for the Bitmap and Metafile classes. 
mage 


System.Drawing.B Encapsulates a GDI+ bitmap, which consists of the pixel data for a graphics image and its attributes. A bitmap is an object used to work 
itmap with images defined by pixel data. 


Table 6-10. Networking 


Class Description 
System.Uri Provides an object representation of a uniform resource identifier (URI) and easy access to the parts of the URI. 


System.Net.NetworkCredentia Provides credentials for password-based authentication schemes such as basic, digest, Kerberos authentication, and 
i NTLM. 


System. Net .Dns Provides simple domain name resolution functionality. 

System. Net .FtpWebRequest Implements a File Transfer Protocol (FTP) client. 

System.Net.HttpWebRequest Provides an HTTP-specific implementation of the WebRequest class. 

System.Net.WebClient Provides common methods for sending data to and receiving data froma resource identified by a URI. 


System.Net.Sockets.TcpClien Provides client connections for TCP network services. 
t 


System.Net.Mail.MailAddress Represents the address ofan electronic mail sender or recipient. 
System.Net.Mail.MailMessage Represents an email message that can be sent using the SmtpClient class. 
System.Net.Mail.SmtpClient Allows applications to send email by using the Simple Mail Transfer Protocol (SMTP). 
System.I0.Ports.SerialPort Represents a serial port resource. 


System.Web. HttpUtility Provides methods for encoding and decoding URLs when processing web requests. 


Class 
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Table 6-11. XML 


Description 


System. Xml.Xm1 Represents a writer that provides a fast, noncached, forward-only way of generating streams or files containing XML data that conforms to 


TextWriter 


the W3C Extensible Markup Language (XML) 1.0 and the namespaces in XML recommendations. 


System. Xm1.Xm1 Represents an XML document. 


Document 


Class 


System.Manag 
ement .Manage 
mentObject 


System.Manag 
ement .Manage 
mentClass 


System.Manag 
ement .Manage 
ment 
ObjectSearch 
er 


System.Manag 
ement .Manage 
mentDateTime 
Converter 


System.Manag 
ement .Manage 
ment 

EventWatcher 


Class 


Table 6-12. Windows Management Instrumentation (WMI) 


Description 


Represents a WMI instance. 


Represents a management class. A management class is a WMI class such as Win32_LogicalDisk (which can represent a disk drive) or 
Win32 Process (which represents a process such as an instance of Notepad.exe). The members of this class enable you to access WMI data 
using a specific WMI class path. For more information, see “Win32 Classes” in the official Windows Management Instrumentation 
documentation. 


Retrieves a collection of WMI management objects based on a specified query. This class is one of the more commonly used entry points to 
retrieving management information. For example, it can be used to enumerate all disk drives, network adapters, processes, and many more 
management objects on a systemor to query for all network connections that are up, services that are paused, and so on. When instantiated, an 
instance of this class takes as input a WMI query represented in an 

ObjectQuery or its derivatives, and optionally a ManagementScope representing the WMI namespace to execute the query in. It can also take 
additional advanced options in an 

EnumerationOptions. When the Get method on this object is invoked, the ManagementObjectSearcher executes the given query in the 
specified scope and returns a collection of management objects that match the query in a ManagementObjectCollection. 


Provides methods to convert DMTF datetime and time intervals to CLR-compliant DateTime and 
TimeSpan formats, and vice versa. 


Subscribes to temporary event notifications based on a specified event query. 


Table 6-13. Active Directory 


Description 


System. DirectoryServices.DirectorySearcher Performs queries against Active Directory. 


System. DirectoryServices.DirectoryEntry 


‘Class 


System. Data.DataSet 


System. Data.DataTable 


The DirectoryEntry class encapsulates a node or object in the Active Directory hierarchy. 


Table 6-14. Database 


Description 
Represents an in-memory cache of data. 


Represents one table of in-memory data. 


System.Data.SqlClient.SqlCommand Represents a Transact-SQL statement or stored procedure to execute against a SQL Server database. 


System.Data.SqlClient. 
SqlConnection 


System.Data.SqlClient. 
SqlDataAdapter 


System. Data. Odbc.OdbcCommand 


System. Data.Odbc.OdbcConnection 


Represents an open connection to a SQL Server database. 

Represents a set of data commands and a database connection that are used to fill the DataSet and update a SQL 
Server database. 

Represents a SQL statement or stored procedure to execute against a data source. 


Represents an open connection to a data source. 


System.Data.Odbc.OdbcDataAdapter Represents a set of data commands and a connection to a data source that are used to fill the DataSet and update 


the data source. 
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Table 6-15. Message queuing 


Class Description 


Provides access to a queue on a Message Queuing server. 
System.Messaging.MessageQueue 


Table 6-16. Transactions 


Class Description 


System.Transactions. Represents a transaction. 
Transaction 
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Chapter 7. WMI Reference 


The Windows Management Instrumentation (WMI) facilities in Windows offer thousands of classes that provide information of interest to 
administrators. Table 7-1 lists the categories and subcategories covered by WMI and can be used to get a general idea of the scope of WMI 
classes. Table 7-2 provides a selected subset of the most useful WMI classes. For more information about a category, search the official WMI 
documentation. 


Table 7-1. WMI class categories and subcategories 


Category Subcategory 


Computer Cooling device, input device, mass storage, motherboard, controller and port, networking device, power, printing, telephony, video, and monitor 
system 
hardware 


Operating COM, desktop, drivers, filesystem, job objects, memory and page files, multimedia audio/visual, networking, operating system events, operating 
system system settings, processes, registry, scheduler jobs, security, services, shares, Start menu, storage, users, Windows NT event log, Windows 
product activation 


WMI WMI configuration, WMI management 

Service 

Managemen 

t 

General Installed applications, performance counter, security descriptor 


Table 7-2. Selected WMI classes 


Class Description 


CIM Dat Represents a named collection of data or executable code. Currently, the provider returns files on fixed and mapped logical disks. In the future, only 
aFile instances of files on local fixed disks will be returned. 


Win32_B Represents a baseboard, which is also known as a motherboard or system board. 
aseBoar 
d 


Win32_B Represents the attributes of the computer system’s basic input/output services (BIOS) that are installed on a computer. 
IOS 


Win32_B Represents the boot configuration ofa Windows system. 
ootConf 

igurati 

on 


Win32_C Represents internal and external cache memory on a computer system. 
acheMem 
ory 


Win32_C Represents a CD-ROM drive on a Windows computer system. Be aware that the name of the drive does not correspond to the logical drive letter 
DROMDri assigned to the device. 
ve 


Win32_C Represents a computer systemin a Windows environment. 
omputer 
System 


Win32_C Represents a product. This includes software and hardware used on this computer system. 
omputer 

SystemP 

roduct 


Win32_D Represents the properties of a DCOM application. 
COMApp1 
ication 


Win32_D Represents the common characteristics ofa user’s desktop. The properties of this class can be modified by the user to customize the desktop. 
esktop 


Win32_D Represents the type of monitor or display device attached to the computer system. 
esktopM 
onitor 


Class 


Win32_D 
eviceMe 
mory 

Address 


Win32_D 
irector 
y 


Win32_D 
iskDriv 
e 


Win32_D 
iskPart 
ition 


Win32_D 
iskQuot 


Win32_E 
nvironm 
ent 


Win32_G 
roup 


Win32_ 
DEContr 
oller 


Win32_ 
ROQResou 
rce 


Win32_L 
oadOrde 
rGroup 


Win32_L 
ogicalD 
isk 


Win32_L 
ogonses 
sion 


Win32_N 
etworkA 
dapter 


Win32_N 
etworkA 
dapter 
Configu 
ration 


WIN32_N 
etworkC 
lient 


Win32_N 
etworkC 
onnecti 
on 


Win32_N 
etworkL 
ogin 

Profile 


Win32_N 
etworkP 
rotocol 
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Description 


Represents a device memory address on a Windows system. 


Represents a directory entry on a Windows computer system. A directory is a type of file that logically groups data files and provides path 
information for the grouped files. Win32_ Directory does not include directories of network drives. 


Represents a physical disk drive as seen by a computer running the Windows operating system Any interface to a Windows physical disk drive is a 
descendant (or member) of this class. The features of the disk drive seen through this object correspond to the logical and management characteristics 
of the drive. In some cases, this may not reflect the actual physical characteristics of the device. Any object based on another logical device would not 
be a member of this class. 


Represents the capabilities and management capacity ofa partitioned area ofa physical disk on a Windows system (for example, Disk #0, Partition #1). 


Tracks disk space usage for NTFS filesystem volumes. A systemadministrator can configure Windows to prevent further disk space use and log an 
event when a user exceeds a specified disk space limit. An administrator can also log an event when a user exceeds a specified disk space warning 
level. This class is new in Windows XP. 

Represents a direct memory access (DMA) channel on a Windows computer system. DMA is a method of moving data froma device to memory (or 
vice versa) without the help of the microprocessor. The system board uses a DMA controller to handle a fixed number of channels, each of which can 
be used by one (and only one) device at a time. 

Represents an environment or system environment setting on a Windows computer system. Querying this class returns environment variables found 
in HKLM\System\CurrentControlSet\Control\Sessionmanager\Environment as wellas HKEY_USERS\<user sid>\Environment. 


Represents data about a group account. A group account allows access privileges to be changed for a list of users (for example, Administrators). 


Manages the capabilities of an integrated device electronics (IDE) controller device. 


Represents an interrupt request line (IRQ) number on a Windows computer system. An interrupt request is a signal sent to the CPU by a device or 
program for time-critical events. IRQ can be hardware- or software-based. 


Represents a group of systemservices that define execution dependencies. The services must be initiated in the order specified by the Load Order 
Group, as the services are dependent on one another. These dependent services require the presence of the antecedent services to function correctly. 
The data in this class is derived by the provider fromthe registry key System\CurrentControlSet\Control\GroupOrderList. 


Represents a data source that resolves to an actual local storage device on a Windows system. 


Describes the logon session or sessions associated with a user logged on to Windows NT or Windows 2000. 


Represents a network adapter of a computer running on a Windows operating system. 


Represents the attributes and behaviors ofa network adapter. This class includes extra properties and methods that support the management of the 
TCP/IP and Internetworking Packet Exchange (IPX) protocols that are independent from the network adapter. 


Represents a network client on a Windows system. Any computer system on the network with a client relationship to the systemis a descendant (or 
member) of this class (for example, a computer running Windows 2000 Workstation or Windows 98 that is part ofa Windows 2000 domain). 


Represents an active network connection in a Windows environment. 


Represents the network login information ofa specific user on a Windows system. This includes but is not limited to password status, access 
privileges, disk quotas, and login directory paths. 


Represents a protocol and its network characteristics on a Win32 computer system. 
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Class Description 


Win32_N Represents a Windows NT domain. 
TDomain 


Win32_N Represents a logical file or directory of Windows NT events. The file is also known as the event log. 
TEventl 


ogFile 


Win32_N Used to translate instances fromthe Windows NT event log. An application must have SeSecurityPrivilege to receive events fromthe security 
TLogEve 


nt 


Win32_0 
nBoardD 


evice 


Win32_0 
peratin 


gSystem 


Win32_0 
SRecove 


y 


Configu 


ration 


Win32_ 


ageFile 
Setting 


Win32_ 


ageFile 


Usage 


Win32_ 


P 


P 


Pp 


erfRawD 
ata Per 
fNet_Se 


rver 


Win32_P 
hysical 


Memory 
Array 


Win32_ 


ortConn 


ector 


Win32_ 


ortReso 


urce 


Win32_ 
rinter 


Win32_ 
rinter 


P 


P 


Configu 


ration 


Win32_ 


rintJob 


Win32_ 
rocess 


Win32_ 


rocesso 


P 


P 


event log; otherwise, “Access Denied” is returned to the application. 


Represents common adapter devices built into the motherboard (system board). 


Represents an operating system installed on a computer running on a Windows operating system. Any operating system that can be installed on a 
Windows systemis a descendant or member of this class. Win32_OperatingSystemis a singleton class. To get the single instance, use @ for the 
key. 


Windows Server 2003, Windows XP, Windows 2000, and Windows NT 4.0: Ifa computer has multiple operating systems installed, this class returns 
only an instance for the currently active operating system. 


Represents the types of information that will be gathered frommemory when the operating system fails. This includes boot failures and system 
crashes. 


Represents the settings ofa page file. Information contained within objects instantiated from this class specifies the page file parameters used when 
the file is created at system startup. The properties in this class can be modified and deferred until startup. These settings are different from the runtime 
state ofa page file expressed through the associated class Win32_PageFileUsage. 

Represents the file used for handling virtual memory file swapping on a Win32 system Information contained within objects instantiated from this 
class specifies the runtime state of the page file. 


Provides raw data from performance counters that monitor communications using the WINS Server service. 


Represents details about the computer system physical memory. This includes the number of memory devices, memory capacity available, and memory 
type (for example, system or video memory). 


Represents physical connection ports, such as DB-25 pin male, Centronics, or PS/2. 


Represents an I/O port on a Windows computer system. 


Represents a device connected to a computer running on a Microsoft Windows operating system that can produce a printed image or text on paper or 
another medium. 


Represents the configuration for a printer device. This includes capabilities such as resolution, color, fonts, and orientation. 


Represents a print job generated by a Windows application. Any unit of work generated by the Print command of an application that is running on a 
computer running on a Windows operating systemis a descendant or member of this class. 


Represents a process on an operating system. 


Represents a device that can interpret a sequence of instructions on a computer running on a Windows operating system. On a multiprocessor 
computer, one instance of the Win32_Processor class exists for each processor. 


Represents products as they are installed by Windows Installer. A product generally correlates to one installation package. For information about 
support or requirements for installation ofa specific operating system, visit the Microsoft developer documentation site and search for “Operating 
System Availability of WMI Components.” 


Win32_Q Represents system-wide Quick Fix Engineering (QFE) or updates that have been applied to the current operating system. 
uickFix 
Enginee 


ring 


Class 


Win32_Q 
uotaSet 
ting 


Win32_R 
egistry 


Win32_S 
chedule 
dJob 


Win32_S 
CSICont 
roller 


Win32_S 
ervice 


Win32_S 
hare 


Win32_S 
oftware 
Element 


Win32_S 
oftware 
Feature 


Win32_S 
oundDev 
ice 


Win32_S 
tartupC 
ommand 


Win32_S 
ystemAc 
count 


Win32_S 
ystemDr 
iver 


Win32_S 
ystemEn 
closure 


Win32_S 
ystemS1 
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Win32_T 
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e 
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Description 


Contains setting information for disk quotas on a volume. 


Represents the systemregistry on a Windows computer system 


Represents a job created with the AT command. The Win32_ScheduledJob class does not represent a job created with the Scheduled Task Wizard 
fromthe Control Panel. You cannot change a task created by WMI in the Scheduled Tasks UI. 


Windows 2000 and Windows NT 4.0: You can use the Scheduled Tasks UI to modify the task you originally created with WMI. However, although the 
task is successfully modified, you can no longer access the task using WMI. 


Each job scheduled against the schedule service is stored persistently (the scheduler can start a job after a reboot) and is executed at the specified time 
and day of the week or month. Ifthe computer is not active or ifthe scheduled service is not running at the specified job time, the schedule service 
runs the specified job on the next day at the specified time. 


Jobs are scheduled according to Universal Coordinated Time (UTC) with bias offset from Greenwich Mean Time (GMT), which means that a job can be 
specified using any time zone. The Win32_ScheduledJob class returns the local time with UTC offset when enumerating an object, and converts to 
local time when creating new jobs. For example, a job specified to run on a computer in Boston at 10:30 p.m. Monday PST will be scheduled to run 
locally at 1:30 a.m. Tuesday EST. Note that a client must take into account whether daylight saving time is in operation on the local computer, and if it 
is, then subtract a bias of 60 minutes fromthe UTC offset. 


Represents a SCSI controller on a Windows system. 


Represents a service on a computer running on a Microsoft Windows operating system. A service application conforms to the interface rules of the 
Service Control Manager (SCM), and can be started by a user automatically at system start through the Services Control Panel utility or by an 
application that uses the service functions included in the Windows API. Services can start when there are no users logged on to the computer. 
Represents a shared resource on a Windows system. This may be a disk drive, printer, interprocess communication, or other shareable device. 
Represents a software element, part of a software feature (a distinct subset ofa product, which may contain one or more elements). Each software 
element is defined in a Win32_SoftwareElement instance, and the association between a feature and its Win32_SoftwareFeature instance is 
defined in the Win32_SoftwareFeatureSoftwareElements association class. For information about support or requirements for installation on a 
specific operating system, visit the Microsoft developer documentation site and search for “Operating System Availability of WMI Components.” 
Represents a distinct subset of a product that consists of one or more software elements. Each software element is defined in a 
Win32_SoftwareElement instance, and the association between a feature and its Win32_SoftwareFeature instance is defined in the 
Win32_SoftwareFeatureSoftwareElements association class. For information about support or requirements for installation on a specific 


operating system, visit the Microsoft developer documentation site and search for “Operating System Availability of WMI Components.” 


Represents the properties of a sound device on a Windows computer system. 


Represents a command that runs automatically when a user logs on to the computer system. 


Represents a systemaccount. The systemaccount is used by the operating systemand services that run under Windows NT. There are many services 
and processes within Windows NT that need the capability to log on internally—for example, during a Windows NT installation. The system account 
was designed for that purpose. 


Represents the system driver for a base service. 


Represents the properties that are associated with a physical system enclosure. 


Represents physical connection points, including ports, motherboard slots and peripherals, and proprietary connection points. 


Represents a tape drive on a Windows computer. Tape drives are primarily distinguished by the fact that they can be accessed only sequentially. 


Represents the properties of a temperature sensor (e.g., electronic thermometer). 
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Class Description 


Win32_T Represents the time zone information for a Windows system, which includes changes required for the daylight saving time transition. 
imeZone 


Win32_U Contains information about a user account on a computer running on a Windows operating system. 
serAcco 


i Because both the Name and Domain are key properties, enumerating Win32_UserAccount on a large network can affect performance negatively. 
un = 


Calling 
GetObject or querying for a specific instance has less impact. 


Win32_V Represents the properties of a voltage sensor (electronic voltmeter). 
oltageP 
robe 


Win32_V Relates disk quota settings with a specific disk volume. Windows 2000/NT: This class is not available. 
olumeQu 

ota 

Setting 


Win32_W Contains the operational parameters for the WMI service. This class can have only one instance, which always exists for each Windows systemand 
MISetti cannot be deleted. Additional instances cannot be created. 


ng 


Chapter 8. Selected COM Objects and Their Uses 


As an extensibility and administration interface, many applications expose useful functionality through COM objects. Although PowerShell 
handles many of these tasks directly, many COM objects still provide significant value. 


Table 8-1 lists a selection of the COM objects most useful to system administrators. 


Table 8-1. COM identifiers and descriptions 


Identifier Description 

Access.Application Allows for interaction and automation of Microsoft Access. 

Agent .Control Allows for the control of Microsoft Agent 3D animated characters. 

AutoItXx3.Control (nondefault) Provides access to Windows Automation via the AutoIt administration tool. 
CEnroll.CEnroll Provides access to certificate enrollment services. 

Certificate Provides access to a request to a certificate authority. 


Authority.Request 


COMAdmin.COMAdminCatal Provides access to and management of the Windows 


og COM+ catalog. 

Excel.Application Allows for interaction and automation of Microsoft Excel. 

Excel .Sheet Allows for interaction with Microsoft Excel worksheets. 

HNetCfg. FwMgr Provides access to the management functionality of the Windows Firewall. 
HNetCf£g.HNetShare Provides access to the management functionality of Windows Connection Sharing. 
HTMLFile Allows for interaction and authoring ofa new Internet Explorer document. 


nfoPath.Application Allows for interaction and automation of Microsoft InfoPath. 


nternetExplorer. Allows for interaction and automation of Internet Explorer. 
Application 

XSSO.Query Allows for interaction with Microsoft Index Server. 

XSSO.Util Provides access to utilities used along with the IXxSSO. Query object. 


LegitCheckControl.Legi Provide access to information about Windows Genuine Advantage status on the current computer. 
tCheck 


MakeCab.MakeCab Provides functionality to create and manage cabinet (.cab) files. 
MAPI.Session Provides access to a Messaging Application Programming Interface (MAPT) session, such as folders, messages, and the address 
book. 


Messenger.MessengerApp Allows for interaction and automation of Messenger. 


Microsoft.FeedsManager Allows for interaction with the Microsoft RSS feed platform. 


Microsoft. ISAdm Provides management of Microsoft Index Server. 
Microsoft.Update. Provides management of the auto update schedule for Microsoft Update. 
AutoUpdate 


Microsoft.Update.Insta Allows for installation of updates from Microsoft Update. 
ller 


Microsoft.Update.Searc Provides search functionality for updates from Microsoft Update. 
her 


Microsoft.Update.Sessi Provides access to local information about Microsoft Update history. 
on 


Microsoft.Update.Syste Provides access to information related to Microsoft Update for the current system. 


mInfo 
MMC20.Application Allows for interaction and automation of Microsoft Management Console (MMC). 
MSScriptControl. Allows for the evaluation and control of WSH scripts. 


ScriptControl 


Identifier 
Msxml2.XSLTemplate 


Outlook.Application 


OutlookExpress.Message 
List 


PowerPoint .Application 
Publisher.Application 
RDS.DataSpace 
SAPI.SpVoice 


Scripting. FileSystemOb 
ject 


Scripting.Signer 
Scriptlet.TypeLib 
ScriptPW. Password 


SharePoint .OpenDocumen 
ts 


un 


hell.Application 


Shell.LocalMachine 


Shell. User 
SQLDMO. SQLServer 
Vim.Application 
WIA.CommonDialog 
WMPlayer .OCX 
Word.Application 
Word. Document 


WScript.Network 


WScript.Shell 


WSHController 
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Description 


Allows for processing of XSL transforms. 


Allows for interaction and automation of your email, calendar, contacts, tasks, and more through Microsoft Outlook. 


Allows for interaction and automation of your email through Microsoft Outlook Express. 


Allows for interaction and automation of Microsoft PowerPoint. 
Allows for interaction and automation of Microsoft Publisher. 
Provides access to proxies of Remote DataSpace business objects. 
Provides access to the Microsoft Speech API. 


Provides access to the computer’s filesystem. Most functionality is available more directly through PowerShell or through 
PowerShell’s support for the .NET Framework. 


Provides management of digital signatures on WSH files. 
Allows the dynamic creation of scripting type library (.//b) files. 


Allows for the masked input of plain-text passwords. When possible, you should avoid this, preferring the Read-Host cmdlet 
with the -AsSecureString parameter. 


Allows for interaction with Microsoft SharePoint Services. 

Provides access to aspects of the Windows Explorer Shell application, such as managing windows, files and folders, and the 
current session. 

Provides access to information about the current machine related to the Windows shell. 
Provides access to aspects of the current user’s Windows session and profile. 
Provides access to the management functionality of Microsoft SQL Server. 
(nondefault) Allows for interaction and automation of the VIM editor. 

Provides access to image capture through the Windows Image Acquisition facilities. 
Allows for interaction and automation of Windows Media Player. 

Allows for interaction and automation of Microsoft Word. 

Allows for interaction with Microsoft Word documents. 


Provides access to aspects ofa networked Windows environment, such as printers and network drives, as well as computer and 
domain information. 


Provides access to aspects of the Windows Shell, such as applications, shortcuts, environment variables, the registry, and the 
operating environment. 


Allows the execution of WSH scripts on remote computers. 


Chapter 9. Selected Events and Their Uses 


PowerShell’s eventing commands give you access to events from the .NET Framework, as well as events surfaced by Windows Management 
Instrumentation (WMI). Table 9-1 lists a selection of .NET events. Table 9-2 lists a selection of WMI events. 


Type 


System. 


System. 


System. 


System. 


System. 


System. 


System. 


Microsoft 


Microsoft. 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


Microsoft 


System. 


System. 


System. 


System. 


System. 


System. 


System. 


AppDomain 


AppDomain 


AppDomain 


AppDomain 


AppDomain 


AppDomain 


Console 


.Win32. 


Win32 


.Win32. 


.Win32. 
-Win32. 
.Win32. 
.Win32. 
.Win32. 
.Win32. 
.Win32. 


.Win32. 


.Win32. 


Net .WebC 


Net .WebC 
Net .WebC 
Net .WebC 
Net. 


WebC 


Net .WebC 


Net .WebC 


SystemEven 


. SystemEven 


SystemEven 


SystemEven 


SystemEven 


SystemEven 


SystemEven 


SystemEven 


SystemEven 


SystemEvent 


SystemEven 


SystemEven 


ient 


ient 


ient 


ient 


ient 


ient 


ient 


tS 


tS 


tS 


tS 


ts 


ts 


CS 


ts 


Table 9-1. Selected .NET events 


Event 


AssemblyLoad 
TypeResolve 


ResourceResolve 


AssemblyResolve 


ReflectionOnly 
AssemblyResolve 


UnhandledExcepti 
on 


CancelKeyPress 
DisplaySettings 
Changing 


DisplaySettingsC 
hanged 


InstalledFontsCh 
anged 


LowMemory 
PaletteChanged 
PowerModeChanged 
SessionEnded 
SessionEnding 
SessionSwitch 
TimeChanged 
UserPreferenceCh 
anged 
UserPreferenceCh 
anging 


OpenReadComplete 
d 


OpenWriteComplet 
ed 


DownloadString 
Completed 


DownloadDataComp 
leted 


DownloadFileComp 
leted 


UploadStringComp 
leted 


UploadDataComple 
ted 


Description 


Occurs when an assembly is loaded. 


Occurs when the resolution ofa type fails. 


Occurs when the resolution of a resource fails because the resource is not a valid linked or 
embedded resource in the assembly. 


Occurs when the resolution of an assembly fails. 


Occurs when the resolution of an assembly fails in the reflection-only context. 


Occurs when an exception is not caught. 


Occurs when the Control modifier key (Ctrl) and C console key (C) are pressed simultaneously 


(Ctr ©). 


Occurs when the display settings are changing. 


Occurs when the user changes the display settings. 


Occurs when the user adds fonts to or removes fonts fromthe system. 


Occurs when the systemis running out of available RAM. 

Occurs when the user switches to an application that uses a different palette. 
Occurs when the user suspends or resumes the system. 

Occurs when the user is logging off or shutting down the system. 

Occurs when the user is trying to log off or shut down the system. 

Occurs when the currently logged-in user has changed 

Occurs when the user changes the time on the systemclock. 


Occurs when a user preference has changed. 


Occurs when a user preference is changing. 


Occurs when an asynchronous operation to open a streamcontaining a resource completes. 


Occurs when an asynchronous operation to open a stream to write data to a resource 


completes. 


Occurs when an asynchronous resource-download operation completes. 


Occurs when an asynchronous data download operation completes. 


Occurs when an asynchronous file download operation completes. 


Occurs when an asynchronous string-upload operation completes. 


Occurs when an asynchronous data-upload operation completes. 
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Type Event Description 

System.Net.WebClient UploadFileComple Occurs when an asynchronous file-upload operation completes. 
ted 

System.Net .WebClient UploadValuesComp Occurs when an asynchronous upload ofa name/value collection completes. 
leted 

System.Net.WebClient DownloadProgress Occurs when an asynchronous download operation successfully transfers some or all of the 
Changed data. 

System.Net.WebClient UploadProgressCh Occurs when an asynchronous upload operation successfully transfers some or all of the data. 
anged 

System.Net.Sockets.Socket Completed The event used to complete an asynchronous operation. 

AsyncEventArgs 


System.Net.NetworkInformation. | NetworkAvailabil Occurs when the availability of the network changes. 
NetworkChange ityChanged 


System.Net.NetworkInformation. | NetworkAddressCh Occurs when the IP address ofa network interface changes. 
NetworkChange anged 


System.10.FileSystemWatcher Changed Occurs when a file or directory in the specified path is changed. 

System. I0.FileSystemWatcher Created Occurs when a file or directory in the specified path is created. 

System. 10.FileSystemWatcher Deleted Occurs when a file or directory in the specified path is deleted. 

System. 1I0O.FileSystemWatcher Renamed Occurs when a file or directory in the specified path is renamed. 

System.Timers.Timer Elapsed Occurs when the interval elapses. 

System. Diagnostics.EventLog EntryWritten Occurs when an entry is written to an event log on the local computer. 

System. Diagnostics. Process OutputDataReceiv Occurs when an application writes to its redirected StandardOutput stream. 
ed 

System. Diagnostics. Process ErrorDataReceive Occurs when an application writes to its redirected StandardError stream. 
d 

System.Diagnostics. Process Exited Occurs when a process exits. 

System. IO.Ports.SerialPort ErrorReceived Represents the method that handles the error event ofa 


SerialPort object. 


System. IO.Ports.SerialPort PinChanged Represents the method that will handle the serial pin changed event ofa 
SerialPort object. 


System. IO.Ports.SerialPort DataReceived Represents the method that will handle the data received event ofa SerialPort object. 


System.Management .Automation.Job StateChanged Event fired when the status ofthe job changes, such as when the job has completed in all 
runspaces or failed in any one runspace. 


System.Management.Automation. DebuggerStop Event raised when PowerShell stops execution of the script and enters the debugger as the 
Debugger result of encountering a breakpoint or executing a step command. 

System.Management .Automation. BreakpointUpdate Event raised when the breakpoint is updated, such as when it is enabled or disabled. 
Debugger d 

System.Management.Automation. StateChanged Event that is raised when the state of the runspace changes. 


Runspaces .Runspace 


System.Management .Automation. AvailabilityChan Event that is raised when the availability of the runspace changes, such as when the runspace 
Runspaces.Runspace ged becomes available and when it is busy. 
System.Management .Automation. StateChanged Event raised when the state of the pipeline changes. 


Runspaces. Pipeline 


System.Management . Automation. InvocationStateC Event raised when the state ofthe pipeline of the PowerShell object changes. 
PowerShell hanged 
System.Management.Automation. DataAdded Event that is fired after data is added to the collection. 


PSDataCollection[T] 


System.Management. Completed Event that is fired when the 
Automation. PSDataCollection[T] Complete method is called to indicate that no more data is to be added to the collection. 
System.Management .Automation. StateChanged Event raised when the state of the runspace pool changes. 


Runspaces.RunspacePool 


Type 


System.Management.Automation. 
Runspaces.PipelineReader [T] 


System.Diagnostics. 


Eventing.Reader.EventLogWatcher 


System.Data 


System.Data 
SqlBulkCopy 


System.Data 


System.Data 


SqlConnection 


System.Data 


SqlConnection 


System.Data 


SqlDataAdapter 


System.Data 


SqlDataAdapter 


System.Data 


SqlDataAdapter 


System.Data 


.Common.DbConnection 


.SqlClient. 


Event 

DataReady 
EventRecordWritt 
en 

StateChange 


SqlRowsCopied 


.SqlClient.SqlCommand StatementComplet 


.SqlClient. 


-SqlClient. 


.SqlClient. 


.SqlClient. 


.SqlClient. 


.-SqlClient. 


SqlDependency 


Generic 


WMI Events 


ed 


InfoMessage 


StateChange 


RowUpdated 


RowUpdating 


FillError 


OnChange 


Some generic WMI events include the following: 


__InstanceCreationEvent 
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Description 


Event fired when data is added to the buffer. 

Allows setting a delegate (event handler method) that gets called every time an event is 
published that matches the criteria specified in the event query for this object. 

Occurs when the state of the event changes. 


Occurs every time that the number of rows specified by the NotifyAfter property have been 
processed. 


Occurs when the execution ofa Transact-SQL statement completes. 


Occurs when SQL Server returns a warning or informational message. 


Occurs when the state of the event changes. 


Occurs during Update after a command is executed against the data source. The attempt to 
update is made, so the event fires. 


Occurs during Update before a command is executed against the data source. The attempt to 
update is made, so the event fires. 


Returned when an error occurs during a fill operation. 


Occurs when a notification is received for any of the commands associated with this Sql 
Dependency object. 


This event class generically represents the creation of instances in WMI providers, such as Processes, Services, Files, and more. 


A registration for this generic event looks like: 


$query = "SELECT * FROM InstanceCreationEvent " + 


"WITHIN 5 


"WHERE targetinstance is a 


"4 


"Win32 UserAccount' 
Register-CimIndicationl 


__InstanceDeletionEvent 


Event -Query $query 


This event class generically represents the removal of instances in WMI providers, such as Processes, Services, Files, and more. 


A registration for this generic event looks like: 


$query = "SELECT * FROM InstanceDeletionEvent " + 


"WITHIN 5 


"WHERE targetinstance is a 


Woy 


"Win32 UserAccount' 
Register-CimIndicationl 


__InstanceModificationEvent 


Event -Query $query 


This event class generically represents the modification of instances in WMI providers, such as Processes, Services, Files, and more. 


A registration for this generic event looks like: 


Squery = "SELECT * FROM _InstanceModificationEvent " 
+ "WITHIN 5 " + 


"WHERE targetinstance is a 


"Win32 UserAccount' 
Register-CimIndicationl 


Event -Query $query 


Event 


Msft_Wmi 
Provider 


Operatio 
nEvent 


Win32_Co 
mputerSy 
stemEven 
E 


Win32_Co 
mputersh 
utdown 
Event 


Win32_IP 
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Table 9-2. Selected WMI Events 
Description 


The Msft_WmiProvider OperationEvent event class is the root definition of all WMI provider events. A provider operation is defined as some 
execution on behalf ofa client via WMI that results in one or more calls to a provider executable. The properties of this class define the identity of 
the provider associated with the operation being executed and is uniquely associated with instances of the class Msft_ Providers. Internally, WMI 
can contain any number of objects that refer to a particular instance of 

__Win32Provider since it differentiates each object based on whether the provider supports per-user or per-locale instantiation and also 
depending on where the provider is being hosted. Currently 

TransactionIdentifier is always an empty string. 


This event class represents events related to a computer system. 


This event class represents events when a computer has begun the process of shutting down. 


The Win32_IP4RouteTableEvent class represents IP route change events resulting fromthe addition, removal, or modification of IP routes on the 
computer system. 


The registry event classes allow you to subscribe to events that involve changes in hive subtrees, keys, and specific values. 


The RegistryKeyChangeEvent class represents changes to a specific key. The changes apply only to the key, not its subkeys. 

The RegistryTreeChangeEvent class represents changes to a key and its subkeys. 

The RegistryValueChangeEvent class represents changes to a single value ofa specific key. 

The SystemTrace class is the base class for all system trace events. Systemtrace events are fired by the kernel logger via the event tracing API. 
This event is the base event for process events. 

The ProcessStartTrace event class indicates a new process has started. 

The ProcessStopTrace event class indicates a process has terminated. 

The ModuleTrace event class is the base event for module events. 


The ModuleLoadTrace event class indicates a process has loaded a new module. 
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Description 


The ThreadTrace event class is the base event for thread events. 


The ThreadStartTrace event class indicates a new thread has started. 


The ThreadStopTrace event class indicates a thread has terminated. 


The Win32_PowerManagementEvent class represents power management events resulting from power state changes. These state changes are 
associated with either the Advanced Power Management (APM) or the Advanced Configuration and Power Interface (ACPI) system management 
protocols. 


The Win32_DeviceChangeEvent class represents device change events resulting from the addition, removal, or modification of devices on the 
computer system. This includes changes in the hardware configuration (docking and undocking), the hardware state, or newly mapped devices 
(mapping ofa network drive). For example, a device has changed when a WM_DEVICECHANGE message is sent. 


The Win32_SystemConfigurationChangeEvent is an event class that indicates the device list on the systemhas been refreshed, meaning a 
device has been added or removed or the configuration changed. This event is fired when the Windows message 
“DevMgrRefreshOn<ComputerName>” is sent. The exact change to the device list is not contained in the message, and therefore a device refresh is 
required in order to obtain the current system settings. Examples of configuration changes affected are IRQ settings, COM ports, and BIOS version, 
to name a few. 


The Win32_VolumeChangeEvent class represents a local drive event resulting fromthe addition ofa drive letter or mounted drive on the computer 
system (e.g., CD-ROM). Network drives are not currently supported. 


Chapter 10. Standard PowerShell Verbs 


Cmdlets and scripts should be named using a Verb-Noun syntax (e.g, Get -ChildItem). The official guidance is that, with rare 
exception, cmdlets should use the standard PowerShell verbs. They should avoid any synonyms or concepts that can be mapped to the 


standard. This allows administrators to quickly understand a set of cmdlets that use a new noun. 


To quickly access this list (without the definitions), type Get-Verb. 


Verbs should be phrased in the present tense, and nouns should be singular. Tables 10-1 through 10-6 list the different categories of standard 
PowerShell verbs. 


Rese 


Table 10-1. Standard PowerShell common verbs 


Meaning 


Adds a resource to a container or attaches an element to another element 


Removes all elements froma container 


Removes access to a resource 


Copies a resource to another name or container 


Sets a resource as a context 


Returns to the context that was present before a new context was entered 


Searches within an unknown context for a desired item 


Converts an itemto a specified structure or layout 


Retrieves data 


Makes a display not visible 
Joins a resource 

Locks a resource 

Moves a resource 

Creates a new resource 
Enables access to a resource 


Increases the effectiveness ofa resource 


Removes an item fromthe top ofa stack 
Puts an item onto the top ofa stack 
Repeats an action or reverts the action of an Undo 


Changes the size ofa resource 


Removes a resource froma container 


Gives a resource a new name 


Restores a resource to a predefined or original state 


Synonyms 
Append, Attach, Concatenate, Insert 


Flush, Erase, Release, Unmark, Unset, Nullify 


Shut, Seal 


Duplicate, Clone, Replicate 


Push, Telnet, Open 


Pop, Disconnect 

Dig, Discover 

Layout, Arrange 

Read, Open, Cat, Type, Dir, Obtain, Dump, 
Acquire, Examine, Find, Search 
Suppress 

Combine, Unite, Connect, Associate 
Restrict, Bar 

Transfer, Name, Migrate 

Create, Generate, Build, Make, Allocate 
Release, Unseal 


Improve, Fix 


Remove, Paste 
Put, Add, Copy 
Repeat, Retry, Revert 


Change, Grow, Shrink 


Delete, Kill 


Ren, Swap 


Restore, Revert 
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Meaning Synonyms 
Sele Creates a subset of data froma larger data set Pick, Grep, Filter 
CE 
Sear Finds a resource (or summary information about that resource) in a collection (does not actually retrieve Find, Get, Grep, Select 


ch the resource but provides information to be used when retrieving it) 


Set Places data Write, Assign, Configure 
Show Retrieves, formats, and displays information Display, Report 
Skip Bypasses an element in a seek or navigation Bypass, Jump 
Spli Separates data into smaller elements Divide, Chop, Parse 
t 
Step Moves a process or navigation forward by one unit Next, Iterate 
Swit Alternates the state ofa resource between different alternatives or options Toggle, Alter, Flip 
ch 
Undo Sets a resource to its previous state Revert, Abandon 
Unlo Unlocks a resource Free, Unrestrict 
ck 
Use Applies or associates a resource with a context With, Having 
Watc Continually monitors an item Monitor, Poll 
h 
Table 10-2. Standard PowerShell communication verbs 
Verb Meaning Synonyms 
Connect Connects a source to a destination Join, Telnet 
Disconnects a source froma destination Break, Logoff 

Disconnect 

Read Acquires information froma nonconnected source Prompt, Get 

Receive Acquires information froma connected source Read, Accept, Peek 

Send Writes information to a connected destination Put, Broadcast, Mail 

Write Writes information to a nonconnected destination Puts, Print 

Table 10-3. Standard PowerShell data verbs 
Verb Meaning Synonyms 
Backup Backs up data Save, Burn 
Checkpoint Creates a snapshot of the current state of data or its configuration Diff, StartTransaction 
Compare Compares a resource with another resource Diff, Bc 
Compress Reduces the size or resource usage of an item Zip, Squeeze, Archive 
Convert Changes from one representation to another when the cmdlet supports bidirectional conversion or conversion of many Change, Resize, 
data types Resample 

ConvertFro Converts fromone primary input to several supported outputs Export, Output, Out 
m 
ConvertTo Converts fromseveral supported inputs to one primary output Import, Input, In 
Dismount Detaches a name entity froma location in a namespace Dismount, Unlink 
Edit Modifies an item in place Change, Modify, Alter 
Expand Increases the size or resource usage of an item Extract, Unzip 
Export Stores the primary input resource into a backing store or interchange format Extract, Backup 


Group 


Combines an item with other related items 


Merge, Combine, Map 


Verb 


Import 
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Meaning 


Creates a primary output resource froma backing store or interchange format 


Initialize Prepares a resource for use and initializes it to a default state 


Limit 


Merge 


Mount 


Out 


Publish 


Restore 


Save 


Sync 


Applies constraints to a resource 

Creates a single data instance from multiple data sets 

Attaches a named entity to a location in a namespace 

Sends data to a terminal location 

Make a resource known or visible to others 

Restores a resource to a set of conditions that have been predefined or set by a checkpoint 
Stores pending changes to a recoverable store 


Synchronizes two resources with each other 


Unpublish Removes a resource from public visibility 


Update 


Verb 
Debug 


Measure 


Ping 
Repair 
Resolve 
Test 


Trace 


Verb 
Approve 
Assert 
Build 
Complet 
e 
Confirm 
Deny 


Deploy 


Disable 
Enable 
Install 
Invoke 


Registe 
i i 


Request 


Restart 


Updates or refreshes a resource 


Table 10-4. Standard PowerShell diagnostic verbs 


Meaning 
Examines a resource, diagnoses operational problems 


Identifies resources consumed by an operation or retrieves statistics about a resource 


Synonyms 


Load, Read 


Setup, Renew, Rebuild 


Quota, Enforce 
Combine, Join 
Attach, Link 


Print, Format, Send 


Deploy, Release, Install 


Repair, Return, Fix 


Write, Retain, Submit 


Push, Update 


Uninstall, Revert 


Refresh, Renew, Index 


Synonyms 


Attach, Diagnose 


Calculate, Determine, Analyze 


Determines whether a resource is active and responsive (in most instances, this should be replaced by the verb Test) Connect, Debug 


Recovers an item froma damaged or broken state 
Maps a shorthand representation to a more complete one 
Verify the validity or consistency ofa resource 


Follow the activities of the resource 


Table 10-5. Standard PowerShell lifecycle verbs 


Meaning 
Gives approval or permission for an item or resource 
Declares the state of an item or fact 


Creates an artifact (usually a binary or document) out of some set of input files (usually source code or declarative 
documents) 


Finalizes a pending operation 


Approves or acknowledges a resource or process 


Disapproves or disallows a resource or process 


Fix, Recover, Rebuild 
Expand, Determine 
Diagnose, Verify, Analyze 


Inspect, Dig 


Synonyms 
Allow, Let 
Verify, Check 


Compile, Generate 


Finalize, End 


Check, Validate 


Fail, Halt 


Sends an application, website, or solution to a remote target[s] in such a way that a consumer of that solution can access Ship, Release 


it after deployment is complete 

Configures an itemto be unavailable 

Configures an item to be available 

Places a resource in the specified location and optionally initializes it 
Calls or launches an activity that cannot be stopped 


Adds an itemto a monitored or publishing resource 


Submits for consideration or approval 


Stops an operation and starts it again 


Halt, Hide 
Allow, Permit 
Setup, Configure 


Run, Call, Perform 


Record, Submit, Journal, 


Subscribe 


Ask, Query 


Recycle, Hup 
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Verb Meaning Synonyms 

Resume Begins an operation after it has been suspended Continue 

Start Begins an activity Launch, Initiate 
Stop Discontinues an activity Halt, End, Discontinue 
Submit Adds to a list of pending actions or sends for approval Send, Post 

Suspend Pauses an operation, but does not discontinue it Pause, Sleep, Break 
Uninsta Removes a resource fromthe specified location Remove, Clear, Clean 
1il 

Unregis Removes an item froma monitored or publishing resource Unsubscribe, Erase, 
ter Remove 

Wait Pauses until an expected event occurs Sleep, Pause, Join 


Table 10-6. Standard PowerShell security verbs 


Verb Meaning Synonyms 

Block Restricts access to a resource Prevent, Limit, Deny 
Grant Grants access to a resource Allow, Enable 
Protect Limits access to a resource Encrypt, Seal 
Revoke Removes access to a resource Remove, Disable 


Unblock Removes a restriction ofaccess to a resource Clear, Allow 


Unprotect Removes restrictions froma protected resource Decrypt, Decode 
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A Guided Tour of PowerShell 


Introduction 


PowerShell has revolutionized the world of system management and command-line shells. From its object-based pipelines to its administrator 
focus to its enormous reach into other Microsoft management technologies, PowerShell drastically improves the productivity of administrators 
and power users alike. 


When you’re learning a new technology, it’s natural to feel bewildered at first by all the unfamiliar features and functionality. This perhaps rings 
especially true for users new to PowerShell because it may be their first experience with a fully featured command-line shell. Or worse, they’ ve 
heard stories of PowerShell’s fantastic integrated scripting capabilities and fear being forced into a world of programming that they’ ve actively 
avoided until now. 


Fortunately, these fears are entirely misguided; PowerShell is a shell that both grows with you and grows on you. Let’s take a tour to see what it 
is capable of 


= PowerShell works with standard Windows commands and applications. You don’t have to throw away what you already know and use. 


= PowerShell introduces a powerful new type of command. PowerShell commands (called cmdlets) share a common Ve rb-Noun syntax 
and offer many usability improvements over standard commands. 


= PowerShell understands objects. Working directly with richly structured objects makes working with (and combining) PowerShell 
commands immensely easier than working in the plain-text world of traditional shells. 


= PowerShell caters to admmistrators. Even with all its advances, PowerShell focuses strongly on its use as an interactive shell: the experience 
of entering commands in a running PowerShell application. 


= PowerShell supports discovery. Using three simple commands, you can learn and discover almost anything PowerShell has to offer. 


= PowerShell enables ubiquitous scripting. With a fully fledged scripting language that works directly from the command line, PowerShell lets 
you automate tasks with ease. 


= PowerShell bridges many technologies. By letting you work with .NET, COM, WMI, XML, and Active Directory, PowerShell makes 
working with these previously isolated technologies easier than ever before. 


= PowerShell simplifies management of data stores. Through its provider model, PowerShell lets you manage data stores using the same 
techniques you already use to manage files and folders. 


We'll explore each of these pillars in this introductory tour of PowerShell. If you’re running any supported version of Windows (Windows 7 or 
later, or Windows 2012 R2 or later), Windows PowerShell is already installed. That said, a significant step up from this default installation is the 
open source PowerShell Core. 


An Interactive Shell 


At its core, PowerShell is first and foremost an interactive shell. While it supports scripting and other powerful features, its focus as a shell 
underpins everything, 

Getting started in PowerShell is a simple matter of launching PowerShell.exe rather than cmd.exe—the shells begin to diverge as you explore 
the intermediate and advanced functionality, but you can be productive in PowerShell immediately. 


To launch PowerShell, click Start and then type PowerShe11 (or pwsh if you’ve jumped ahead!). 


A PowerShell prompt window opens that’s nearly identical to the traditional command prompt of its ancestors. The PS _C:\Users\Lee> 
prompt indicates that PowerShell is ready for input, as shown in Figure P-1. 


104 


BY Windows PowerShell = X 


Copyright (C) Microsoft Corporation. All rights reserved, 


Try the new cross-platform Powershell https://aka.ms/pscore6 


PS C:\Users\lee> _ 


Figure P-1. Windows PowerShell, ready for input 


Once you’ve launched your PowerShell prompt, you can enter DOS- and Unix-style commands to navigate around the filesystem just as you 
would with any Windows or Unix command prompt—as in the interactive session shown in Example P-1. In this example, we use the pusha, 
cd, dir, pwd, and popd commands to store the current location, navigate around the filesystem, list items in the current directory, and then 
return to the original location. Try it! 


Example P-1. Entering many standard DOS- and Unix-style file manipulation commands produces the same results you get when you 
use them with any other Windows shell 

PS C:\Users\Lee> function prompt { "PS >" } 

PS > pushd . 

PS > cd \ 

PS > dir 


Directory: C:\ 


Mode LastWriteTime Length Name 

d---- 5/8/2007 8:37 P Blurpark 
d---- 5/15/2016 4:32 P Chocolatey 
d---- 3/8/2020 12:45 P DXLab 

d---- 4/30/2020 7:00 Al Go 

d---- 4/2/2016 3:05 P Intel 

d-r-- 12/15/2020 1:41 P Program Files 
d-r-- 11/28/2020 5:06 P Program Files (x86) 
d---- 5/12/2019 6:37 P Python27 
d---- 3/25/2018 1:11 PB Strawberry 
d---- 12/16/2020 8:13 Al temp 

d-r-- 8/11/2020 5:02 P Users 

da--- 12/16/2020 10:51 Al Windows 

PS > popd 

PS > pwd 

Path 


C:\Users\Lee 


In this example, our first command customizes the prompt. In cmd.exe, customizing the prompt looks like prompt $PS$G. In Bash, it looks 
Ike PS1="{\h] \w> ". In PowerShell, you define a function that returns whatever you want displayed. 
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The pushd command is an alternative name (alias) to the much more descriptively named PowerShell command Push-Location. 


Likewise, the cd, dir, popd, and pwd commands all have more memorable counterparts. 


Although navigating around the filesystem is helpful, so is running the tools you know and love, suchas ipconfig and notepad. Type the 
command name and you'll see results like those shown in Example P-2. 


Example P-2. Windows tools and applications such as ipconfig run in PowerShell just as they do in cmd.exe 


PS > ipconfig 


Windows IP Configuration 


Ethernet adapter Wireless Network Connection 4: 


Connection-specific DNS Suffix . : hsdl.wa.comcast.net. 
IP Address. .......... . : 192.168.1.100 
Subnet Mask e s e œ o w o w e œ > $ 255.255.255.0 
Default Gateway ........ . : 192.168.1.1 


PS > notepad 
(notepad launches) 


Entering ipconfig displays the IP addresses of your current network connections. Similarly, entering notepad runs—as yov’ d expect— 
the Notepad editor that ships with Windows. Try them both on your own machine. 


Structured Commands (Cmdlets) 


In addition to supporting traditional Windows executables, PowerShell introduces a powerful new type of command called a cmdlet 
(pronounced “command-let’”). All cmdlets are named ina Verb-Noun pattern, suchas Get -Process, Get-Content, and Stop- 
Process: 


PS > Get-Process -Name lsass 
Handles NPM(K) PM(K) WS (K) VM(M) CPU (s) Id ProcessName 


668 13 6228 1660 46 932 lsass 


In this example, you provide a value to the ProcessName pararreter to get a specific process by name. 


NOTE 


Once you know the handful of common verbs in PowerShell, learning how to work with new nouns becomes much easier. While you 
may never have worked with a certain object before (such as a Service), the standard Get, Set, Start, and Stop actions still apply. For 
a list of these common verbs, see Table 10-1 in Chapter 10. 


You don’t always have to type these full cmdlet names, however. PowerShell lets you use the Tab key to autocomplete cmdlet names and 
parameter names: 


PS > Get-Pro<TAB> -N<TAB> lsass 


For quick interactive use, even that may be too much typing. To help improve your efficiency, PowerShell defines aliases for all common 
commands and lets you define your own. In addition to alias names, PowerShell requires only that you type enough of the parameter name to 
disambiguate it from the rest of the parameters in that cmdlet. PowerShell is also case-insensitive. Using the built-in gp s alias (which represents 
the Get -Process cmdlet) along with parameter shortening, you can instead type: 


PS > gps -n lsass 


Going even further, PowerShell supports positional parameters on cmdlets. Positional parameters let you provide parameter values in a certain 
position on the command line, rather than having to specify them by name. The Get -Process cmdlet takes a process name as its first 
positional parameter. This parameter even supports wildcards: 


PS > gps 1*s 


Deep Integration of Objects 
PowerShell begins to flex more of its muscle as you explore the way it handles structured data and richly functional objects. For example, the 
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following command generates a simple text string. Since nothing captures that output, PowerShell displays it to you: 


PS > "Hello World" 
Hello World 


The string you just generated is, in fact, a fully functional object from the .NET Framework. For example, you can access its Length 
property, which tells you how many characters are in the string. To access a property, you place a dot between the object and its property 
name: 


PS > "Hello World".Length 
11 


All PowerShell commands that produce output generate that output as objects as well. For example, the Get -Process cmulet generates a 
System.Diagnostics.Process object, which you can store ina variable. In PowerShell, variable names start with a $ character. If 
you have an instance of Notepad running, the following command stores a reference to it: 


Sprocess = Get-Process notepad 


Since this is a fully functional Process object fromthe .NET Framework, you can call methods on that object to perform actions on it. This 
command calls the Ki 11 () method, which stops a process. To access a method, you place a dot between the object and its method name: 


Sprocess.Kill () 


PowerShell supports this functionality more directly through the St op-Process cmdkt, but this example demonstrates an important point 
about your ability to interact with these rich objects. 


Administrators as First-Class Users 


While PowerShell’s support for objects ftom the .NET Framework quickens the pulse of most users, PowerShell continues to focus strongly on 
administrative tasks. For example, PowerShell supports MB (for megabyte) and GB (for gigabyte) as some of its standard administrative 
constants. How many GIF memes will fit in a 800 GB hard drive? 


PS > 800GB / 2.2MB 
372363 . 636363636 


Although the .NET Framework is traditionally a development platform, it contains a wealth of functionality useful for administrators too! In fact, 
it makes PowerShell a great calendar. For example, is 2096 a leap year? PowerShell can tell you: 


PS > [DateTime] ::IsLeapYear (2096) 
True 


Going further, how might you determine how much time remains until the Y2038 Epochalypse? The following command converts 
"01/19/2038" (the date of the Year 2038 problem) to a date, and then subtracts the current date from that. It stores the result in the 
$result variable, and then accesses the Total Days property: 


PS > $result = [DateTime] "01/19/2038" - [DateTime] : :Now 
PS > Sresult.TotalDays 
6242 . 49822756465 


Composable Commands 


Whenever a command generates output, you can use a pipeline character (|) to pass that output directly to another command as input. If the 
second command understands the objects produced by the first command, it can operate on the results. You can chain together many 
commands this way, creating powerful compositions out ofa few simple operations. For example, the following command gets all items in the 
Path! directory and moves them to the Path2 directory: 


Get-Item Path1\* | Move-Item -Destination Path2 


You can create even more complex commands by adding additional cmdlets to the pipeline. In Example P-3, the first command gets all 

processes running on the system. It passes those to the Whe re-Object cmdlet, which runs a comparison against each incoming item. In this 
case, the comparison is $_ . Handles -ge 500, which checks whether the Handles property of the current object (represented by the 
$_ variable) is greater than or equal to 500. For each object in which this comparison holds true, you pass the results to the Sort-Object 
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cmdlet, asking it to sort items by their Handles property. Finally, you pass the objects to the Format-Table cmdkt to generate a table 


that contains the Handles, Name, and Description ofthe process. 


Example P-3. You can build more complex PowerShell commands by using pipelines to link cmdlets, as shown here with Get-Process, 
Where-Object, Sort-Object, and Format-Table 


PS > Get-Process | 
Where-Object { $ .Handles -ge 500 } | 
Sort-Object Handles | 
Format-Table Handles,Name, Description -Auto 


Handles Name Description 

588 winlogon 

592 svchost 

667 lsass 

725 csrss 

742 System 

964 WINWORD Microsoft Office Word 
1112 OUTLOOK Microsoft Office Outlook 
2063 svchost 


Techniques to Protect You from Yourself 


While aliases, wildcards, and composable pipelines are powerful, their use in commands that modify system information can easily be nerve- 
racking. After all, what does this command do? Think about it, but don’t try it just yet: 


PS > gps [b-t]*[c-r] | Stop-Process 


It appears to stop all processes that begin with the letters b through t and end with the letters c through r. How can you be sure? Let 
PowerShell tell you. For commands that modify data, PowerShell supports -what If and -Con firm parameters that let you see what a 
command would do: 


PS > gps [b-t]*[c-r] | Stop-Process -whatif 

What if: Performing operation "Stop-Process" on "ctfmon (812)". 
What if: Performing operation "Stop-Process" on "Ditto (1916)". 
What if: Performing operation "Stop-Process" on "dsamain (316)". 
What if: Performing operation "Stop-Process" on "ehrecvr (1832)". 
What if: Performing operation "Stop-Process" on "ehSched (1852)". 
What if: Performing operation "Stop-Process" on "EXCEL (2092)". 
What if: Performing operation "Stop-Process" on "explorer (1900)". 


In this interaction, using the -wha t I £ parameter with the Stop-Process pipelined command lets you preview which processes on your 
system will be stopped before you actually carry out the operation. 


Note that this example is not a dare! In the words of one reviewer: 


Not only did it stop everything, but on one of my old machines, it forced a shutdown with only one minute warning! 


It was very funny though...At least I had enough time to save everything first! 


Common Discovery Commands 


While reading through a guided tour is helpful, I find that most learning happens in an ad hoc fashion. To find all commands that match a given 
wildcard, use the Get -Command cmudlet. For example, by entering the following, you can find out which PowerShell commands (and 
Windows applications) contain the word process: 


PS > Get-Command *process* 


CommandT ype Name Definition 

Cmdlet Get-Process Get-Process [[-Name] <Str... 
Application qprocess.exe c:\windows\system32\qproc... 
Cmdlet Stop-Process Stop-Process [-Id] <Int32... 


To see what a command such as Get -Process does, use the Get -He1p cmdket, like this: 


PS > Get-Help Get-Process 
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Since PowerShell lets you work with objects from the .NET Framework, it provides the Get -Membe r cmdlet to retrieve information about 


the properties and methods that an object, such as a .NET System.String, supports. Piping a string to the Get -Member command 
displays its type name and its members: 


PS > "Hello World" | Get-Member 


TypeName: System.String 


Name lemberType Definition 

(Saw) 

PadLeft ethod System.String PadLeft (Int32 tota... 
PadRight ethod System.String PadRight (Int32 tot... 
Remove Method System.String Remove (Int32 start... 
Replace ethod System.String Replace (Char oldCh... 
Sprit ethod System.String[] Split (Params Cha... 
StartsWith ethod System.Boolean StartsWith (String... 
Substring ethod System.String Substring (Int32 st... 
ToCharArray Method System.Char[] ToCharArray(), Sys... 
ToLower ethod System.String ToLower(), System.... 
ToLowerInvariant Method System.String ToLowerInvariant () 
ToString Method System.String ToString(), System... 
ToUpper lethod System.String ToUpper(), System.... 
ToUpperInvariant Method System.String ToUpperInvariant () 
Trim Method System.String Trim(Params Char[]... 
TrimEnd lethod System.String TrimEnd(Params Cha... 
TrimStart lethod System.String TrimStart (Params C... 
Length Property System.Int32 Length {get; } 


Ubiquitous Scripting 


PowerShell makes no distinction between the commands typed at the command line and the commands written in a script. Your favorite 
cmdlets work in scripts and your favorite scripting techniques (e.g., the foreach statement) work directly on the command line. For example, 
to add up the handle count for all running processes: 


PS > ShandleCount = 0 

PS > foreach ($process in Get-Process) { 
ShandleCount += Sprocess.Handles } 

PS > ShandleCount 

19403 


While PowerShell provides a command (Measure-Ob ject) to measure statistics about collections, this short example shows how 
PowerShell lets you apply techniques that normally require a separate scripting or programming language. 


In addition to using PowerShell scripting keywords, you can also create and work directly with objects from the .NET Framework that you may 
be familiar with. PowerShell becomes almost like the C# immediate mode in Visual Studio. Example P-4 shows how PowerShell lets you easily 
interact with the .NET Framework. 


Example P-4. Using objects from the .NET Framework to retrieve a web page and process its content 


PS > SwebClient = New-Object System.Net.WebClient 
PS > $content = S$webClient.DownloadString ( 
"https: //devblogs.microsoft.com/powershell/feed/") 

PS > Scontent.Substring (0,1000) 

<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" 
xmlns:content="http://purl.org/rss/1.0/modules/content/" 
xmlns:wfw="http: //wellformedweb.org/CommentAPI/" 
xmlns:dc="http://purl.org/dc/elements/1.1/" 
xmins:atom="http://www.w3.org/2005/Atom" 
xmlns:sy="http://purl.org/rss/1.0/modules/syndication/" 
xmlns:slash="http://purl.org/rss/1.0/modules/slash/" > 

<channel> 
<title>PowerShell</title> 
<atom:link href="https://devblogs.microsoft.com/powersh..." 
<link>https://devblogs.microsoft.com/powershell</link> 
<description>Automating the world one-liner at a time... 
</description> 


Ad Hoc Development 
By blurring the lines between interactive administration and writing scripts, the history buffers of PowerShell sessions quickly become the basis 
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for ad hoc script development. In this example, you call the Get -History cmdkt to retrieve the history of your session. For each item, you 


get its CommandLine property (the thing you typed) and send the output to a new script file. 


PS > Get-History | ForEach-Object { 
$ .CommandLine } > c:\temp\script.ps1 
PS > notepad c:\temp\script.psl 
(save the content you want to keep) 
PS > c:\temp\script.psl 


NOTE 


If this is the first time you’ ve run a script in PowerShell, you’ ll need to configure your execution policy. 


Bridging Technologies 
We’ve seen how PowerShell lets you fully leverage the .NET Framework in your tasks, but its support for common technologies stretches even 
farther. As Example P-5 (continued from Example P-4) shows, PowerShell supports XML. 


Example P-5. Working with XML content in PowerShell 
PS > SxmlLContent = [xml] $content 
PS > SxmlContent 


xml xml-stylesheet rss 


version="1.0" encoding... type="text/xsl" href="... rss 


PS > SxmlContent.rss 


version : 2.0 
content : http://purl.org/rss/1.0/modules/content/ 


wfw : http://wellformedweb.org/CommentAPI/ 

dc : http://purl.org/dc/elements/1.1/ 

atom : http://www.w3.org/2005/Atom 

sy : http://purl.org/rss/1.0/modules/syndication/ 
slash : http://purl.org/rss/1.0/modules/slash/ 


channel : channel 


PS > $xmlContent.rss.channel.item | select Title 


PowerShell 7.2 Preview 2 release 

Announcing PowerShell Crescendo Preview.1 

You’ve got Help! 

SecretManagement preview 6 and SecretStore preview 4 
Announcing PowerShell 7.1 

Announcing PSReadLine 2.1+ with Predictive IntelliSens 
Updating help for the PSReadLine modul 

PowerShell Working Groups 

(E 


PowerShell also lets you work with Windows Management Instrumentation (WMI) and Common Information Model (CIM): 


PS > Get-CimInstance Win32 Bios 


SMBIOSBIOSVersion : ASUS A7N8X Deluxe ACPI BIOS Rev 1009 


Manufacturer : Phoenix Technologies, LTD 
Name : Phoenix - AwardBIOS v6.00PG 
SerialNumber $ XXXXXXXXXXX 

Version : Nvidia - 42302e31 


Or, as Example P-6 shows, you can work with Active Directory Service Interfaces (ADSI). 


Example P-6. Working with Active Directory in PowerShell 
PS > [ADSI] "WinNT://./Administrator" | Format-List * 


UserFlags : {66113} 
MaxStorage 5 t=1} 
PasswordAge : {19550795} 


PasswordExpired : {0} 
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255-259 -255-255 255 255 255 255 255 


LoginHours : 
255 255.255 255 255 255 255 255 255 
255 255 255} 

FullName : {} 

Description Built-in account for administering 
the computer/domain} 

BadPasswordAttempts 5 {0} 

LastLogin : {5/21/2007 3:00:00 AM} 

HomeDirectory } 

LoginScript } 

Profile } 

HomeDirDrive } 

Parameters } 

PrimaryGroupID 513} 

Name Administrator} 

MinPasswordLength 0 

laxPasswordAge 3710851} 

inPasswordAge 0 

PasswordHistoryLength 0 

AutoUnlockInterval : {1800} 

LockoutObservationInterval : {1800} 

MaxBadPasswordsAl lowed = {0 

RasPermissions sf 

objectSid 15000005 21000 121 227 


252 83 122 130 50 34 67 23 10 50 
244 1 0 0} 


Or, as Example P-7 shows, you can even use PowerShell for scripting traditional COM objects. 
Example P-7. Working with COM objects in PowerShell 


PS > $firewall = New-Object -com HNetCfg.FwMgr 
PS > $firewall.LocalPolicy.CurrentProfile 


Type a aL 

FirewallEnabled : True 

Except ionsNotAllowed : False 

otificationsDisabled : False 

UnicastResponsesToMulticastBroadcastDisabled : False 

RemoteAdminSettings : System. ComObject 

IcmpSettings : System. _ComObject 

GloballyOpenPorts {Media Center 
Extender Service, 
Remote Media Center 
Experience, Adam 
Test Instance, 
QWAVE...} 

Services {File and Printer 


Sharing, UPnP 
Framework, Remote 
Desktop} 

{Remote Assistance, 
Windows Messenger, 
Media Center, 
Trillian...} 


AuthorizedApplications 


Namespace Navigation Through Providers 


Another avenue PowerShell offers for working with the system is providers. PowerShell providers let you navigate and manage data stores 
using the same techniques you already use to work with the filesystem, as illustrated in Example P-8. 


Example P-8. Navigating the filesystem 


PS > Set-Location c:\ 
PS > Get-ChildItem 


Directory: C:\ 


Mode LastWriteTime Length Name 

d---- 5/8/2007 8:37 PM Blurpark 

d---- 5/15/2016 4:32 PM Chocolatey 

d---- 3/8/2020 12:45 PM DXLab 

d---- 4/30/2020 7:00 AM Go 

d---- 4/2/2016 3:05 PM Intel 

d-r-- 12/15/2020 1:41 PM Program Files 
d-r-- 11/28/2020 5:06 PM Program Files (x86) 
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d---- 5/12/2019 6:37 PM Python27 
d---- 3/25/2018 1:11 PM Strawberry 
d---- 12/16/2020 8:13 AM temp 

d-r-- 8/11/2020 5:02 PM Users 
da--- 12/16/2020 10:51 AM Windows 


This also works on the registry, as shown in Example P-9. 
Example P-9. Navigating the registry 


PS > Set-Location HKCU: \Software\Microsoft\Windows\ 
PS > Get-ChildItem 


Hive: HKEY_CURRENT_USER\Software\Microsoft\Windows 


Name Property 

CurrentVersion 

DWM Composition aL 
ColorPrevalence : 0 
ColorizationColor : 3290322719 
EnableAeroPeek pL 
AccentColor : 4280243998 
EnableWindowColorization HL 

Shell 

TabletPC 


Windows Error Reporting 


PS > Set-Location CurrentVersion\Run 
PS > Get-ItemProperty . 


(ania) 


OneDrive : "C:\Users\lee\AppData\Local\Microsoft\OneDriv... 
/background 

OpenDNS Updater : "C:\Program Files (x86) \OpenDNS Updater\OpenD... 
/autostart 

Ditto : C:\Program Files\Ditto\Ditto.exe 


ETES) 
And it even works on the machine’s certificate store, as Example P-10 illustrates. 


Example P-10. Navigating the certificate store 


PS > Set-Location cert:\CurrentUser\Root 
PS > Get-ChildItem 


Directory: Microsoft.PowerShell.Security\ 
Certificate: :CurrentUser\Root 


Thumbprint Subject 


T 


A43489159A520F0D93D032CCAF37E7FE2 CN=Microsoft Root Authority, 


CDD4EEAE6000AC7F40C3802C171E30148 CN=Microsoft Root Certificate... 
E36A4562FB2EE05DBB3D32323ADF4450 CN=Thawte Timestamping CA, OU... 


9FE47B4D05D46E8066BAB1DIBFC9E48F1 CN=PowerShell Local Certifica... 


7E88CD7223F3C813818C994614A89C99F CN=Microsoft Authenticode (tm)... 
245C97DF751 4E7CE2DF8BE72AE957B9EO OU=Copyright (c) 1997 Microso... 


